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Section 1 


INTRODUCTION 


Prepared as a single source reference for the application programmer, this 
manual covers the system features most directly related to application 
programming. On-line documentation, FORTRAN considerations, file 
management, and system references are briefly described. Sections are 
arranged to correspond with the sequence of creating and executing 
application code. The loader, compiler, subroutine trace, and application 
debugger are presented in depth, along with system data formats, and 


system subroutines. 


The Table of Contents and Index provide quick reference to material. 

Subroutines may be referenced by name, in the Table of Contents, or by 

function, in the Brief Subroutine Description section (Section 4). This 
_ publication is divided into six sections: 


Section Title 


1 INTRODUCTION 


2 CREATING 
EXECUTABLE 
CODE 


3 DEBUGGING 


4 BRIEF SUBROUTINE 


DESCRIPTIONS 


5 SUBROUTINES 


6 SYSTEM FORMATS 


Contents 


Notation, access, levels, and com- 
mands for on-line documentation. 


Step-by-step information on compil- 
ing and loading code; symbol tables, 
loader commands, and FORTRAN 
considerations are all included. There 
are sample files of loader commands, 
with directions for loading. Command 
execution and system references are 
also discussed. 


An in-depth description of the 
Subroutine Trace tool and Applica- 
tion Debugger. 


System subroutines, described and 
grouped by function. 


System subroutines for applications 
programming, presented in a detailed 


_-alphabetical list. 


Data and storage formats. 
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This manual contains many examples of subroutine and command syntax. 
Differing type sizes and faces are used to distinguish between system and 
user responses. 


e USER INPUT 
Exact Variable 
ALL CAPS. Upper and Lower Case. 


e SYSTEM OUTPUT 


Exact Variable 
ALL CAPS, Upper and Lower Case 
SMALL TYPE FACE. Small Type Face. 


e OTHER CONVENTIONS 


) Carriage return. 

n> Operating System (O/S) level 
prompt for input. 

[ ] Square brackets contain optional 
material. 

{ } Braces contain two or more items, 


only one of which may be chosen. 


x _ A subscripted lowercase x at the end 
of a number enclosed in single quota- 
tion marks indicates a hexadecimal 
value (e.g., ‘8C5’x). 


The following aspects of on-line documentation are described: access, 
levels, listing of documents, examples, and special commands. 


To access on-line documentation, type the HELP command in response to 
a prompt at the Operating System (O/S) level (n>). Documentation will 

_ be printed on the user COMDEV. While the HELP program is running, a ?] 
will ask for user input. A carriage return ) in response to the ?] exits HELP 
and returns user to O/S level. 


Levels 


Listing 
Documents 
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HELP uses multiple levels of documentation to explain various features of 
the O/S: 


HELP (level 0) 
yoy oN 
/ | \ 
/ \ \ 
name sname2 framed (level 1) 
/ / 
/ / x 
name3 framed name7 (level 2) 
/ \ 
/ \ 
jname6 name8 (level 3) 
fs | x 
/ | \ 
name9 name10 nameit1 (level 4) 


Each name (name2, name4, named, name6) may have a text document 
and further sub-category levels beneath it. Terminating names (name, 
name3, name7, name8, name9, name10, name11) are documents without 
further sub-categories. | 


From any level, only documentation at lower levels can be referenced. To 
get this documentation, type the name of the document in response to the 
?]. If the name typed has further sub-categories, you are moved to the next 
level. If the name is a document with no further sub-categories, you 
remain at the same level. 


From level 0 (HELP), the following commands will enable you to access 
the documents described. 


Command Description 
name Name printed; you remain at 
level 0. 
name2 Name2 printed; you go to level 


1; the next level (name3) Is listed 
for your choice of documents. 


name4 named Name5d printed; you go to level 
2; and documents at the next 
level (name6, name8)are listed. 


name2 name3 Name3 printed; you remain at 
level 0 (name3 has no_ sub- 
categories). 
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Examples These commands, in response to the level 0 HELP prompt ?], will access 
the documents described. 


Command | Description 


?] INFO FORTRAN Information about FORTRAN/S 
is printed; you remain at level 0. 


?] SUBROUTINE FILL Information about the subroutine 
“FILL” is printed; you remain at 
level 0. For information on any 
system subroutine mentioned 
here, just type: 


o> HELP SUBROUTINE Subroutinename ) 
In response to the O/S prompt. 


Special Several commands make accessing documents more convenient. 
Commands _ These commands are typed in response to the ?] prompt instead of a 
name: 
/L Lists the sub-categories and documents at the current — 
level. 
/B Backs up one level and lists the sub-categories and 


documents at that level. 


/R Repeats the last text document printed. 
/Q Leaves HELP to return to the O/S. 
/S and /A HELP has two sets of documentation; system documen- 


tation and other (CADDS, user, etc.) documentation. 


/S Places you at level 0 of System documentation (the level 
of initial access to HELP). 


/A Accesses the alternate set of documentation, and puts 
you at level 0. This alternate set includes everything but 
System documentation. In order to return to System 
documentation, you must type /S. 


HELP Prints this document. 
Returns to O/S level. 

(Carriage 

Return) 
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Section 2 


CREATING EXECUTABLE CODE 


CREATING EX- This is an overview of the steps involved in creating and executing appli- 

ECUTABLE CODE cation code on the CV Graphics Operating System (CGOS). Application 
code, as used in this manual, refers to any programs written to run in the 
graphics environment. 


Use the text editor to enter new routines onto the system (See the 
CGOS 200 GNA Operator Guide for text editor documentation). In 
general, an application program will consist of several routines. For a 
program stored as unbundled code, each routine should have a 
separate file. For bundled code, write the routine to the file 
CADDS.OVLY (Bundled and unbundled code are further described 
elsewhere in this section). 


Compile each new routine separately. One way to compile is to exit 
the editor with a File and Compile (FC) command. The compiler out- 
puts a symbol map that is useful for debugging. 


Re-edit the file to eliminate any errors encountered during compila- 
tion. Repeat the editing/compilation process until each routine 
compiles without errors. You will now have a file of object code for 
each routine. These files are compietely independent until loading 
resolves external references. 


To load a program, you must first create a text file containing loader 
commands (a Make file). Reference each file to be loaded by specify- 
ing the file containing Its object code. Use standard load libraries to 
resolve references to system library routines. 


Enter the LOAD command from O/S level. Unless the NOTRACE 
option of the loader is used, the loader symbol tables will be saved; 
these tables are useful for debugging your program. The loader links 
each object module within the specified core area. At this point, an 
executable module exists. 


To execute application code on a trial basis, use the TEST command 
for bundled code or the RUN PROG command for unbundled code. In 
this example, CLD9001 is used as a sample coreload number. To 
execute bundled code (O/S level): 


n>CADDS )} | 
#SEL DEBUG DIR Dirname ADD Dirname//NLEV } 
#TEST CLD9001 } 
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Special 
Considerations 


Arrays 


COMPILATION 


Compiling 
Routines 


SYNTAX 
PURPOSE 


OPTIONS 
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To execute unbundled code (O/S level): 


n>CADDS ) 
#RUN PROG Filename ) 


The special considerations deal primarily with overlays, and the arrays 
discussion deals with numbering and referencing. 


When user-written FORTRAN routines are included in an overlay created 
to run on CGOS 200 GNA, the overlay should also include the routines in 
the load library LOADLIB.FORTLIB. These routines support the execution 
of FORTRAN programs. LOADLIB.FORTLIB should be included in any 
Make which loads FORTRAN subroutines. 


In this manual, array numbering follows FORTRAN conventions. Indices 
begin at one (instead of zero as in TPL). To reference these arrays from 
TPL, just subtract one from the array index (i.e., OPTIONS(1) in FOR- 
TRAN is referenced as OPTIONS(0) in TPL). 


Since arrays are referenced differently in TPL than in FORTRAN, use the 
system resident routines CMBYTT, LDBYTT, LDCHRT, MVBYTT, 
STBYTT, and STCHRT to manipulate bytes or characters from TPL pro- 
grams. From FORTRAN programs, use CMBYTF, LDBYTF, LDCHRF, 
MVBYTF, STBYTF, and STCHRF. 


The method of compiling routines and the compiler symbol map are 
discussed. 


COMPILE filename [/OPTION1 { ,OPTION2, _OPTIONn ) 
Compiles a TPL or FORTRAN source file. 


As follows (abbreviations in parentheses): 


LIST List source program and symbol map but not insert 
files. 

LISTIN Same as LIST but also lists insert files. 

LO List object code and symbol map. 


MAPONLY (M) List symbol map only. 


NOFILE Do not file object program. 


CONDCOMP (C) 


NEWCAT (N) 
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Note 


The CONDCOMP option is treated differently 
in each language. In FORTRAN/S, the com- 
piler replaces the (#) character with a blank. 
This makes it impossible to use a five-digit 


statement number with the CONDCOMP . 


option. In TPL, the compiler removes the (#) 
character by shifting the entire source line 
one character to the left. 


Example 


If NEWCAT = T Is specified and the compiler 
needs a file to read, it prefixes ‘’T.’’ to the 
filename and searches for that file. The file 
will be used if it exists. Otherwise the com- 
piler will try to access the file originally named 
(no T prefix). If neither file exists, the 
compiler gives an error and halts. 


Note 


When a user lacks access to an object file and 
NEWCAT is specified, the NEWCAT name 


will be prefixed to the object filename. 


Compiles source lines from the source program that 
begin with the (#) character. (Without CONDCOMP, 
lines that begin with (#) are not compiled.) COND- 
COMP is typically used for debugging. 


Ordinarily, when a source or insert file is referenced, 
the compiler begins its search in the highest level 
catalog of the tree structure (the SYSCATLG). 
NEWCAT designates a catalog that will be searched 
before the SYSCATLG. 
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DECL Default setting that lists all undeclared symbolic 
; names. A symbolic name is undeclared if it is not a 
subroutine name or a statement label and is not 

defined in any of the following kinds of statements: 


FORTRAN/S TPL 
SUBROUTINE E:F D:T 
~ FUNCTION E:O B:D 

COMMON G:L V:S 
DIMENSION D:N SUBR 
INTEGER I:R ENTR 
REAL F:T EQU 
DOUBLE INTEGER D:R TEQ 
DOUBLE PRECISION | 
EXTERNAL 
DATA 

FUNC ° Lists all undeclared symbolic names in the source 


program (including external functions and 
subroutines). 


USED | Default setting for listing any unused symbolic 
names that do not appear in executable code or as 
TPL symbolic constants. 


Note 


DECL and USED are debugging aids for 
uncovering typographical errors that might 
otherwise go unnoticed. The compiler 
defaults to these two options. 


BRIEF (B) Minimizes compiler output messages by suppressing 
messages generated by the DECL and USED 
options 
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The compiler outputs a symbol map as part of the compilation process. 
Where applicable, the symbol map lists a location, a mode, a reference 
type, a dimension, and an equivalence for symbolic names used in the 
source program or insert file. These are output to the COMDEV in 
columns, under the headings LOC, MOD, REF, DIM, and EQUIV. 


Heading 


LOC 


MOD 


Table 2-1 
Elements of a Symbol Map 


Description 


Location is based on six different characteristics and 
depending on the type of symbolic name. Each is listed and 
described briefly below: 


Local variables — the offset from 0 in the low data area. 


Global variables and external subroutines (External 
Symbols) — The value is a two-digit hex index assigned 
by the compiler, which assumes that External Symbol is 
defined somewhere outside the source program. During 
compilation, the first External Symbol is assigned the 
value of ‘FF’x, the second is assigned ‘FE’x, the third 
“FD’x, and so on. The loader uses the index values to 
resolve all references to External Symbols. 


TPL statement labels, internal subroutines, or subroutine 
entry point names — the offset from the start of the 
code. 


FORTRAN equivalenced variables — the offset from the 
start of the base symbol listed under EQUIV. 


TPL based variables — pointer location ts listed. 


TPL symbolic constants — lists value of constant 
instead of its location. 


Abbreviations, in the column under MOD and the row of a 
symbolic name, are as follows: 


F 
I2 


Integer variable. 
Floating point variable. 


Double integer (32-bit) variable. 


F2 Double precision floating point variable. 
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Table 2-1 , 
‘Elements of a Symbol Map (Continued) 


Heading | Description 


REF | Abbreviations under REF refer to the following types of 
symbolic names: 

L Local variable. 

A Dummy argument. 

B _~*TPL based variable. 

G_ Global variable. 

XS___External subroutine. 

SE Subroutine entry point. 

FE FORTRAN function entry point. 

IS Internal subroutine. 

IF FORTRAN internal function. 

LB TPL statement label. 

C TPL symbolic constant. 

DIM _ Refers to the dimension of a variable, where applicable: 

e Array variables — DIM is the number of elements in 
the array. For a TPL array dimensioned with an 
asterisk(*), however, DIM is — 1. DIM will be one less for 
a TPL array than for a FORTRAN array. 


EXAMPLE (For an array of 19 elements): 


FORTRAN TPL 
DIM DIM 
ARRAY 19 ARRAY 18 
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LOADING CODE 


Creating the 
Make File 


Table 2-1 
Elements of a Symbol Map (Continued) 


Heading Description 
e Scalar variables — there is no dimension. 


e FORTRAN COMMON block — the total number of 
words in the block. | 


EQUIV Base symbol usea in calculating the location of a 
FORTRAN equivalenced variable. 


Object code is linked and loaded according to commands in a text file. The 
CGOS loader processes this text file (called a Make file) to tie together 
each file of code and all external references. 


The O/S command LOAD activates the linking loader. LOAD references a 
Make file containing loader commands that designate: 


e Files containing subroutines and functions to be loaded. 
e The overlay into which object code Is loaded. 

e Linkage for system references in the object code. 

e Global areas. 


These commands map out an area of core along with the code and data to 
be put in this area. 


When LOAD is successfully executed, object files are linked together to 
form an overlay (coreload) stored on disc. The overlay is composed of 
binary code in an executable form. 


The following general rules apply in the creation of a Make file: 


e Lines beginning with an asterisk(") | in column 1 are ignored by the 
loader as comment lines. 


e No biank lines are allowed. 


¢ FORTRAN common blocks are indicated by a C& and the common 
block name. 
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Loader Keywords 


BLOCK 


CORORG 


28 


e All values (Val1,Val2,etc.) in the Make file are hexadecimal numbers. 


e Prefix a zero to hexadecimal values with a first significant digit of A-F 
(i.e., F57C must appear as OF57C). 


e Alphabetic values are in ‘‘quotes’’. They are always packed two to a 
word and are left-justified. 


The following loader keywords are valid commands for the Make file: 
BLOCK Val1,Val2 


Declares a region of core allotted to code and data from loader commands 
that follow: 


e Val1 Lower bound of the block (inclusive). 
e Val2 Upper bound of the block (exclusive). 


BLOCK causes'an END-OF-BLOCK condition on the previous block. 


Under an end-of-block condition, the loader compares the amount of core 
left in block to the block size. One of two messages is printed: 


XXXX WORDS AVAILABLE IN BLOCK 


denotes adequate space. If inadequate space remains for code and data, 
the message: 


OVERFLOWED BLOCK BY XXXX WORDS 


will be printed as soon as the overflow is detected. When a block has 
overflowed during loading, WRITE, OVWRITE, CWRITE, and EXECUTE 
commands are not processed. 


CORORG Vali [,Val2] 


Allocates internal buffer space to the overlay created by the Make. Vali is 
the lowest address available to the Make. That is, no BLOCK command 
may define a block that starts below Val1. Val2 may be omitted and will 
default to the value 8000 — Valix. Vali + Val2 is the highest address that 
my be set by the Make. That is, no BLOCK command may define a flock 
that ends above Vali + Val2. 


CWRITE 


DUMP 


END 


ENDC 


ELSE 


EQU 
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CWRITE Val1, Val2, Val3 


Writes the core image to disc and causes an end-of-block condition. After 
completing the disc write, the loader exits to O/S level. The core image is 
stored in the file named in the FILENAME statement. At O/S level, this file 
can be executed with the RUN command. CWRITE accepts the following 
arguments: 


Val1 © Number of words in the overlay. (This is the number of words 
that will be written out to the disc.) 


Val2 Starting core location of the overlay. When the overlay is run, 
this will be the starting address of the executable code. 


Val3. Highest core address used when the overlay is executed. The 
loader will check to ensure that there is sufficient memory 
available for the task to execute the overlay. 


DUMP Val1, Val2 


Prints overlay locations from address Val1 to address Val2 as a standard 
hex dump. 


Signifies the end of a text file. The loader interprets it in either of two 
ways: 


e As the end of an insert file. 
e As a command to return to O/S level without filing the Make overlay 
to disc. 


Marks the termination of a group of conditional loader commands. Condi- 
tional commands must begin with an IF. It is illegal to have an ENDC 
command without a matching IF command. 


A conditional statement used after an IF to enable execution of code when 
the IF condition is false. ELSE appears before the ENDC statement (see 
example under IF). 


EQU Sym Vall[,Val2] 
Defines symbols; the symbol SYM Is assigned the value Val1 unless Sym is 
already defined (see also REDEF and UNDEF. If Val2 is used, Val1 is. 


assumed to be a subroutine address and Val2 is the number of arguments 
required by the subroutine. 
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FILENAME Filename 


Specifies the overlay file to be used by WRITE, OVWRITE, or CWRITE. 
This overlay file may be overridden by another FILENAME command, or by 
the PRIMARY, OVCAT, or DEBUG loader options. If FILENAME is omit- 
ted, the overlay filename will default to the Make filename. — 


FILL Symbol = Value 


Sets initial values for an array of memory locations within the overlay being 
loaded. The array defined by Symbol will be set to Value for each word 
assigned to the array by a GLOBAL statement. | 


IF Condition 


In conjunction with ENDC, IF controls processing of other loader com- 
mands. Commands between the IF and ENDC delimiters are processed 
only if Condition is true. If Condition is false, no subsequent loader 
commands will be processed until a matching ENDC or an ELSE is found. 
CONDITION may be any combination of BOOLEAN EXPRESSIONS and 
OPERATORS. 


BOOLEAN Expressions FORTRAN Equivalents 
Vali = Val2 TRUE IF Val1 .EQ. Val2 
Val1 # Val2 TRUE IF Vali .NE. Val2 
Vali < Val2 TRUE IF Vali .LT. Val2 
Val1 > Val2 TRUE IF Val1 .GT. Val2 
Val1 < Val2 TRUE IF Val1 .LE. Val2 
Val1 < Val2 TRUE IF Val1 .GE. Val2 
OPERATORS: 


Several operators are available for loader Make files. They are classified as 
Integer or Boolean depending on the type of value they return. Boolean 
operators are AND, NOT, OR, UNDEFP, and UNUSEDP. Integer 
operators are SIZE, LAND, and MAX. 


The syntax for operators is: 
[Operator Arg1, Arg2,...Argn] 
Square brackets and the first argument are mandatory. Other arguments 


may be optional, depending on the operator. Use commas with multiple 
arguments. 


INSERT 
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e Boolean 


AND 


NOT 


OR 


UNDEFP 


UNUSEDP 


® Integer 


LAND 


MAX 


SIZE — 


EXAMPLE: 


True when each of the following arguments is true, other- 
wise false. 


Takes one argument and returns its logical negation. 


True when any of the following arguments Is true, other- 
wise false. 


Takes one symbol name and returns true if the symbol nas 
been defined and false otherwise. 


Takes one symbol name and returns true if the symbol has 
been used and false otherwise. 


Takes an arbitrary number of integer arguments and does 
a bitwise AND, returning the result. 


Returns the largest of an arbitrary number of integer 
arguments. Two’s complement signed comparisons are 
used. 


Returns the number of words of storage occupied by one 
symbol. 


IF [OR [UNDEFP Label1],[SIZE Label2] = 2] 


ELSE 


ENDC 


INSERT Filename 


Designates an additional file to include in the Make. The loader stops pro- 
cessing the original Make file to process the entire insert file of loader 
commands. When an END command is encountered in the insert file, the 
loader resumes processing the original Make file. 
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LOAD 


LOADLIB 
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GLOBAL Symi (Val1), . . .,Symn (Valn) 


Defines and allocates global variables. Sym is the name of each global 
variable and the corresponding Val is the length in bytes (dimension) of the 
block of core to allocate for Sym. Val must appear; even a value of 1 must 
be stated explicity (see the SEP and NOSEP commands). 


Note 


Use a value of zero to allocate a global of zero 
words. For example: GLOBAL X(0) is the 
same as EQU X for the last core location used 
for a global, or for code allocation. 


~ LIB Filename 


Searches a load library (specified by Filename) for unresolved subroutine 
references. Only unresolved references will be loaded from the library. 


Default setting for listing symbols in a table as they are created. LISTSYM 
and NLISTSYM drive a counter that is initially set to zero. Whenever sym- 
bols are created and the counter is less than one, those symbols are listed 
in the table. When the counter is greater than or equal to one, symbols are 
not listed. NLISTSYM adds one to the counter; LISTSYM subtracts one 
from the counter. 


LOAD Catalog/File1, . . .,Filen 
Loads object code from a list of object files in the same catalog. The 
resulting absolute binary code is placed into the current block. The name 
of the file and the addresses of the code and data sections from that file are 
added to the listing in this format: 

Catalog. File1 XXXX  XXXX  XXXX_ 

(See the SEP and NOSEP commands.) 
LOADLIB Filename/Subr1,Subr2.... 


Loads specific routines from the load library specified by Filename. 


LOADSYM 


NLISTSYM 


NOSEP 


OVWRITE 


PRINT 
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LOADSYM Filename 

Replaces the current loader symbol table with the symbol table saved in 
the file specified with LOADSYM. A loader symbol table file can only be 
created with SAVESYM. LOADSYM should be used at the start of the 
Make, before any other symbols are created. 

Inhibits the symbol table listing (See LISTSYM). 

Invokes NOSEP mode of loading (SEP mode is the default setting). In 
NOSEP mode, all code and data is loaded at the start of the block (low 
addresses). The following loading rules apply: 

LOAD Code section at start of block. Globals are immediately after 
the code section. The data section is immediately after the 
globals. 

GLOBAL _ Globals at start of block. 

TV TVs at start of block. 

OVWRITE Val1,Val2,Val3 


Writes the overlay to disc. Instead of exiting to O/S level after completing 
the disc write, the loader will continue to process the Make file. 


Val1 DLOC within the file for writing the overlay. 


Val2 Number of words in the overlay. (This is the number of 
words that will be written out to the disc.) 


Val3 Starting core location of the overlay. 
PRINT Text string 
Adds one-line messages to the output. Any text following the PRINT 
keyword will be output literally to the COMDEV when the routine is 


loaded. This message cannot be inhibited with any setting of the loader 
LIST option. 
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REDEF 


SAVESYM 


SEP 


SET 
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REDEF Sym Val 


Defines symbols. Unlike EQU, it does not discriminate against previously- 
defined symbols. REDEF Sym Val ts equivalent to: 


UNDEF Sym followed by EQU Sym Val. 
SAVESYM Filename 


Saves the current loader symbol table in a file that can be referenced and 
re-used with LOADSYM. 


Most Makes begin with one or more “‘standard” insert files. Those insert 
files often define symbols that are common to these “’standard’’ Makes. 
Rather than process the insert files as the first part of every Make, it is 
more efficient to process the insert files and save the resulting symbol table 
in a file. That file can then be used by every Make that would otherwise use 
the insert files to re-create the symbol table. 


Invokes the SEP mode of loading (SEP mode is the default). In SEP mode, 
code is loaded at the start of the block (low addresses); data is loaded at 
the end of the block (high addresses). The following rules apply for loading 
in SEP mode: 


LOAD Code section at start of block. 
Globals at end of block. 
The data section is at the end of the block (before the 
globals). 


GLOBAL  Globals at end of block. 
TV TV's are at the start of the block. 


SET Sym=Val1,. . .,Valn 
or 
SET Sym (Offset) = Val1,. . .,Valn 


Assigns memory locations within the overlay to values (Val1,..Valn). Sym 
is a global, and up to 15 values can be specified. Val1..Valn are assigned to 
memory locations beginning at the position of Sym plus Offset. As in TPL 
indexing, Offsets start at zero for the first word of the global (Offset 
defaults to zero). 


UNDEF 


WRITE 


Running the 
Loader 


SYNTAX 


Creating Executable Code 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


TV Symi, . . .,Symn 


Allocates transfer vectors (see Loader Glossary). The TV command is 
unusual in that it allows references to symbols that are not yet defined. 
One two-word TV is allocated for each symbol in the list. 


TVs are generally used to reserve entry points to overlay routines, and are 
therefore defined immediately following a BLOCK command. The TV com- 
mand allows the programmer to reference a routine without knowing in 
advance where it will be loaded into memory. | 


UNDEF Sym1,. . .,Symn 


Ensures that symbols in the argument list are undefined. Any undefined 
symbols are created, and existing symbols lose their definitions so that 
they may be redefined. 


WRITE Val1, Val2, Val3, Val4, Val5 


Writes the overlay to disc and causes an end-of-block condition. On com- 
pletion of the disc write, the loader exits to O/S level. The core image is 
stored in the file named in the FILENAME statement. At O/S level, this file 
can be executed with the RUN command. WRITE accepts the following 


arguments: 

Val1 The DLOC within the file that the Susiiay will be written out 
to. 

Val2 (Not used) 

Val3 (Not used) 

Val4 Number of words in the overlay. (This is the number of 
words that will be written out to the disc.) 

Val5 Starting core location of the overlay. 


To activate the loader, use the O/S command LOAD. 


LOAD [Make file[/OPTIONS]] 
Make file Text file containing loader commands. 


To enter loader commands from the COMDEV instead of a MAKE file, just 
type: LOAD ) and then type them in. 
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Options must be preceded by a slash. When more than one option is 
entered, each option must be separated by a comma. OPTIONS are as 
follows: 


NEWCAT Format: 


NEWCAT = Catname 
or 
N = Catname 


Ordinarily, when a file is referenced, the loader begins its 
search in the SYSCATLG. This option specifies the name 
of a catalog to search before SYSCATLG. 


EXAMPLE: 

LOAD Makefile/NEWCAT = Catname 
e Reading 

The statements: 


LOAD Filename. 
INSERT Filename. 
LIB Filename. 
LOADLIB Filename. 
LOADSYM Filename. 


cause the loader to read a file. With NEWCAT = Cat- 
name, the loader will search for the _ file: 
Catname. Filename. If that file does not exist, the loader 
will try to read the file Filename. If neither file exists, the 
loader gives an error and returns to the O/S. 


( 


e Writing 


The loader writes to a file when it encounters one of the 
following statements: ; 


WRITE Filename. 
CWRITE Filename. 
OVWRITE Filename. 
SAVESYM Filename. 
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OVCAT 


DEBUG 


NOFILE 


NOTRACE 


LIST 


BRIEF 


lf NEWCAT = Catname is specified and the file 
Catname.Filename exists, it will be overwritten by a 
new file. Otherwise, the file Filename is created and 
written. 


Format: 


OVCAT = Catname 


Activates a special mode of loading, used for debugging 
CADDS. Filenames specified within the Make are ignored. 
The overlay is always written to the file named 
“Catname.Make filename” at disc address zero. The 
CADDS overlay manager is equipped to handle overlays 
written using the OVCAT option. 


Format: 

DEBUG = Catname 
DEBUG is a combination of the NEWCAT and OVCAT 
options (i.e., DEBUG = T is equivalent to NEWCAT = T, 
OVCAT = T). 


RESTRICTION: Only one of these options (NEWCAT, 
OVCAT or DEBUG) may be specified. 


Loads and tests an overlay without writing it to disc. The 
message: 


**TEST RUN** 
is printed when loading is completed. 
Disables saving of the loader symbol file. Symbolic entry 
point names will not be available for access by the DEBUG 
and TRACE commands. (For Trace and Debug informa- 


tion, see Section 3.) 


Activates listing of the Make file and loader symbol 
map — useful for finding typing mistakes in the Make file. 


Suppresses listing of available block space, along with 
output from any DUMP keywords in the Make file. 
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Loader Glossary 


Loader Errors 
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LISTIN 


MAPONLY 


CORE 
IMAGE 


CORELOAD 


GLOBAL 


INSERT 
FILE 


MAKE 
FILE 


OBJECT 
FILE 


OVERLAY 


SOURCE 


TV 


Turns on listing of the Make file, loader symbol map, and 
all insert files. 


Turns on listing of the loader symbol map. 


A stream of bits, whose “‘final’’ destination is in memory. 
A core image is usually executed as machine instructions. 


An overlay containing a module of executable graphics 
code, a coreload is the result of successful execution of 
the LOAD command. 


A variable available to more than one subroutine. 


A text file containing loader commands; the Insert file is 
included in a Make using the loader command INSERT. 


A text file containing loader commands 


A binary output file from a compiler that will be processed 
by the loader is called an object file or object program. 


A file containing a core image 


A program or subroutine that is in the form of a text file is 
called a source file or a source program (see OBJECT). 


An abbreviation for transfer vector. A TV uses two words 
of memory to create the assembly language instruction for 
a GOTO. The first word is a.““JMP @.+1”. The second © 
word is a core address. A subroutine call to the location of 
the TV is equivalent to a subroutine call to the address in 
the second word of the TV. 


Loader error messages are contained in three files listed below. These files 
divide the errors into three categories. Diagnostic errors are the least 
serious, Minor errors are more serious, and Major errors cause the Loader 
to abort processing of the current Make and return to O/S level. Please 
refer to on-line documentation if there is any question regarding codes and 


messages. 

Message File Error Range 
SYSNEWS.ERROR.LOADER.MAJOR (8001-8052) 
SYSNEWS.ERROR.LOADER.MINOR (8080-9092) 
SYSNEWS.ERROR.LOADER.DIAGNOSTICS (80D1-80D5) 
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The following list contains error numbers and associated error messages. 
All error numbers are hexadecimal values. 


e Loader Diagnostic Errors 


80D2 


80D4 


80D5 


An external reference fill-in chain starts at location zero. This 
occurs when an external reference must be loaded into a 
block starting at 0000. 


Object file references a GLOBAL that was not defined as a 
GLOBAL. A GLOBAL must be defined using a Loader 
GLOBAL command or allocated when an object file is 
loaded. 


A subroutine call or definition has the wrong number of 
arguments. There are three frequent causes: 


e The subroutine was previously defined and a call uses a 
different number of arguments. 


e The subroutine was previously called and a call uses a 
different number of arguments. 


e The subroutine was previously called and a Seen 
specifies a different number of arguments. 


e Loader Minor Errors 


8080 Attempt to change the mode of a symbol. 

8081 Attempt to set ESI to a value greater than ‘FF’. 

8086 Object file entry point is already defined. 

8088 Format error in object file: last word is not the end-of-file flag 
(‘FFFF’). 

808A Internal checksum error in object file. 

808B External checksum error in object file. 

808C the object file being loaded is referring to a global that is 
smaller than the declaration in the source file. 

808D Bad character where a slash is expected in a LOAD or 
LOADLIB command. 

S0O8E Load library file is not a loader data file. 

S08F Load library file is a loader data file but does not contain a 
load library. | 

8090 Load library file is in an old format that cannot be used by the 
current version of the loader. 

8091 File to be loaded is not a TYPE 2 (object) file. 

8092 Extra characters at the end of a Loader command line. 
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e Loader Major Errors 
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8001 Attempt to read the size of a symbol that is not a global. 

8002 Attempt to execute when a block has overflowed. 

8005 Attempt to store a word at an address outside of internal 
buffer space allocated in the CORORG command. This error 
is due to an attempt to load a program or initialize a global at 
a bad address. 

8006 Attempt to read a word from an illegal address — this 
indicates that the current block or an earlier block has 
overflowed. 

800D Format error in object file — data block has a bad count. 

800E Set location block in object file trying to set location at a 
symbol that is not yet defined. This error occurs when TPL 
source code tries to data initialize (vector values) a global of 
indefinite length (dimensioned with a *) and the location of 
that global is not yet defined. 

8010 Internal error in object file. 

8011 Bad character where a slash (/) is expected in the Loader 
(O/S) command line. 

8012  CORORG command specifies a block outside the range 
0000-8000. 

8013. INSERT command in an insert file (it is illegal to use nested 
INSERTs). 

8015 Bad character where an equal sign (=) is expected in a FILL 
command. | | 

8016 Symbol in a global command is already defined. 

8017. Bad character where a parenthesis [) or (] is expected in a 
global command. 

8018 Bad character where a comma (,) is expected in any of the 
following commands: GLOBAL, SYM, TV, or UNDEF. 

8019 Illegal function. 

801A Attempt to execute when a symbol is not defined. | 

801B Bad character where a right square bracket (]) is expected in 
a function expression. 

801C Symbol specified in a SET command has an undefined 
location. 

801D Bad character where a right parenthesis [)] is expected in a 


SET command. 
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801E Bad character where an equal sign (=) is expected in a SET 
command. 

801F Attempt to define a symbol that already has a definition 
using an EQU command. 

8021 Bad loader command: keyword not recognized. 

8022 Illegal option on LOADER (O/S) command line. 

8023 Overlay file will be bigger than ‘FFFF’ sectors. 

8024 Internal loader error, attempt to define a symbol that is 
already defined. 

8028 Symbol table overflow: too many symbols have been 
created. 

8029 XRWAD table overflow. 

802A Too many total entry points, called subroutines and globals 
referenced from an object file. 

802B Attempt to execute with low end of CORORG buffer below 
2000x or high end above 8000x. Low end of CORORG buffer 
is the address following the ‘CORORG’ keyword in the Make 
file. The high end defaults to. 

8000x unless specified in the CORORG command line. 

802C Start address specified in an execute command has an 
address outside the overlay that was created. 

802D NEWCAT was specified in the Loader command line, but the 
overlay file cannot be modified because it is in use. 

802E Block to be written to disc overlaps the overlay as defined in 
CORORG command. | 

802F Left parenthesis [(] in an expression does not have a 
matching right parenthesis [)]. | 

8030 Symbol referenced in an expression is not defined. 

8031 Two operators or two operands in a row in an expression. 

8032 Null strings are illegal. 

8033 Command does not have enough numerical arguments. 

8034 Command has too many numerical arguments. 

8035 First operand of a Boolean expression is a string longer than 
two characters. 

8036 Illegal Boolean operator. 

8037 Second operand of a Boolean expression Is a string longer 


than two characters. 
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803B Entry point not found in load library. 

803C Internal loader error. 

803E Attempt to data-initialize a global using a SET command 
exceeds the limits of the global. | 

803F ESI jump instruction address falls outside of address range 
(—128 to +27 words). 

8040 Low data section of object file has exceeded 100x. The 
loader will expand the low data section of an object file in. 
order to create linkages to other subroutines and to globals. 
The resulting size after expansion cannot be larger than . 
100x. This error condition can usually be satisfied by moving 
local integer arrays into a common area (FORTRAN) or con- 
verting them to globals (TPL), then recompiling the object 
file and reloading. 

8042 Overlay filename not specified. 

8043 Overlay file is larger than ‘FFFF’ sectors long. 

8044 An object file created from a TPL source file has referred to a 
global of indefinite length (using a * declaration), but the 
global is undefined when the object file is loaded. 

8045 Attempt to save a symbol table containing an undefined 
symbol. | | 

8046 Filename not specified in LOADSYM or SAVESYM 
command. 

8047 ‘File specified for a LOADSYM command is not a loader data 
file. 

8048 File specified for a LOADSYM command is not a saved 

| symbol table. 

8049 Symbol table in the file specified fora LOADSYM command 
is in an old format and cannot be used by the current version 
of the loader. 

804A File specified for a LOADSYM command has a bad 
checksum. 7 

804B Arguments to BLOCK command are in the wrong 


order — the starting address of the block is larger than the 
ending address of the block. 
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804C No more lines in input file — this can happen when there is 
no END command to terminate an insert file, or when a 
Make file is not terminated by a CWRITE, END, EXECUTE, 
or WRITE command. 


804E BLOCK command specifies a block outside of addressable 
memory. 


804F Attempt to allocate a negative number of words 
— GLOBAL command may have specified a bad global size. 


8050 FILL statement is data initializing a symbol that is not a 
GLOBAL. 


8051 SET statement is data initializing a symbol that is not a 
GLOBAL. 


8052 Function value is not an integer. 


8083 Object file is incompatible with the current version of the 
loader because it was compiled with an old version of the 
compiler. 
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LOADLIB 

COMMAND ~ LOADLIB 

PURPOSE Creates a load library. 
SYNTAX LOADLIB Filename [/options] 


COMMENTS A load library is a collection of object files merged into one and indexed by 
entry point name. There are three reasons for grouping object files in this 
way: 


e Speed — using the LOADLIB command in a Make, object files can be 
loaded directly from the load library. This speeds up the loading pro- 
cess by reducing access to the file manager. 


e Ease of use — in a Make, the LIB command accesses the load library 
created with LOADLIB. LIB is also used to access the standard load 
libraries: — 


CADDSLIB 
FORTLIB 
OSLIB 


These standard libraries should always be referenced in this order, 
otherwise some subroutine references may remain undefined. LIB 


directs the loader to resolve undefined subroutine references by 
loading necessary object files from a load library. 


e One file replaces many files — packing many small files into one big 
file reduces the amount of disc space needed for libraries of object 
files. It also reduces the time required to save (or restore) those object 
files on tape. 


FILENAME Before calling LOADLIB, create a text file containing the LOADLIB 
commands: | 


ADD Catalog/Filename! [,Filename2. . .] 


Adds the object files Catalog.Filename1, Catalog. Filename2 (etc.) to the 
new load library. 


ADDCAT Catalog 


Adds the entire catalog to the load library. 
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FILENAME Filename 


Names the load library file. In the Make, Filename is the name used to 
reference the load library. Use the FILENAME command exactly once in 
each load library. If there is more than one FILENAME command, the last 
one wins. The default filename is the name of the LOADLIB text file. 


OPTIONS LIST [= Hexnum] 


Controls the type of listing produced by LOADLIB. The hex number is a bit 
mask; each bit designates items to be added to the listing. 


Mask Meaning, List: 

1 Input filename. 

2 Input text file (first pass). 

4 Object filenames (first pass). 
8 Entry point names (first pass). 
10 Object filenames (second pass). 
20 Entry point names (second pass). 
40 Load library filename. 


If list is specified without a value: 
LOADLIB Filename/LIST 


LOADLIB defaults to listing the Input filename and the Load library 
filename. 


LISTLOAD 


searches a text file for commands that reference other files. From these 
command references, a list of files is created and output to a file or the 
COMDEV. Optionally, LISTLOAD can generate a system command for 
each file referenced. 


LISTLOAD searches a text file for keywords. These keywords are loader 
(Make) commands that reference other files. Generally the text file is a 
MAKE file, but LISTLOAD can also search a source file for the /INCLUDE 
compiler command. Optional arguments control which commands will be 
searched for. LOAD, INSERT, LOADSYM, and LIB are all commands that 
tell the loader to access a file or set of files. They are also arguments to 
LISTLOAD. 
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SYNTAX 


OUTPUT 
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LISTLOAD 


KEYWORDS 


OPTIONS 


Output filename/KEYWORDSI,OPTIONS] 


Separate multiple keywords with a comma. There are no 
default keywords. Keywords are: 


LOAD 


INSERT 


LOADSYM 


LIB 


LILL 


INCLUDE 


Include files referenced in LOAD commands. 


Include files referenced in INSERT com- 
mands. 


Include files referenced in LOADSYM com- 
mands. | : 


include files referenced in LIB commands. 


Process all types of files specified in the 
above options. 


INCLUDE files from source code referenced 
by /INCLUDE statements. 


Control the output of LISTLOAD: 


COMDEV 


GENCOM 


Output list of files to COMDEV, may not be 
used as a single option or with GENCOM. 


Generate a system command for each file 
referenced, may not be used as a single 
option or with COMDEV. 


LISTLOAD will respond to the initial command line with a prompt: 


# 


This prompt indicates that the user should type a catalog name. 


EXAMPLE: 


1> LISTLOAD CAB.TEST.LIST/COMDEV,LOAD INCLUDE 


#CAB.TEST 


@ COMDEV 


When the COMDEV option is declared, LISTLOAD prints out names 
of appropriate files in the catalog. 
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EXAMPLE: 


1> LISTLOAD LL.TEST.LIST/GENCOM,LOAD 
- ENTER COMMAND SKELETON 
PRINTLP $$ ()) 
#> MAKE.COMMAND.LOAD ) 


#4 
1> 
e GENCOM 
In response to the GENCOM option, LISTLOAD prints: 


ENTER COMMAND SKELETON 


Enter the desired command followed by at least one space and one or 
two pairs of dollar signs. If two pairs are used, commands will be 
generated in the following format: 


MOVE $$, CAB.$$ 


After a carriage return, LISTLOAD prompts the user for a catalog 
name. 


Once the preceding example is executed, the first few lines of 
LL.TEST will look like: 


PRINTLP COMMAND.LOAD.ALLOC 
PRINTLP COMMAND.LOAD.DIAGERR 


PRINTLP COMMAND.LOAD.DOINDEX 
PRINTLP COMMAND.LOAD.GETADDR 


In the output file, LOADLIST replaces the GENCOM command “$$” 
with each filename. 


e Mulltiple Catalogs 


When LOADLIST is finished processing the original catalog, it will 
prompt for another catalog with: | 


# 


A carriage return, will invoke the output phase of LISTLOAD. When 
output is complete, LISTLOAD will return to O/S level. 
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Scans a source file or catalog to generate an index of entry points, globals, 


or subroutines. 


GENINDX {ENTPNTS,GLOBALS,SUBRS \ [/OPTIONS] 


ENTPNTS 
GLOBALS 
SUBRS 


Files associated with each entry point. 
GLOBALS and files that reference them. 
Subroutines referenced by each file. 


One or more of the following entries, separated by commas: 


NOSORT | 
PRINT 


NOFILE 


UTIL 


MRGCOPY 
PSTAT 
SINGLE 
MULTIPLE 


After scanning 


After generating file, do not sort generated entries. 


Print each line as it is added to the file. 


-Do not generate an output file. No operation will be 


performed if NOFILE is chosen without PRINT. 


Effective only with index type SUBRS. Include subroutines 
that have the final level of names begin with &. (This 
includes compiler-generated calls to run-time library in file). 


‘If SORT pass generates multiple lines with identical sort 


fields, blank out sortfield in all except the first line. 


Print status information during sort pass, if sort pass is 
included. 


SORT pass suppresses listing of multiple entries with iden- 
tical sort fields. 


Only SORT pass generated multiple entries with identical 
sort fields are included in output listing. 


the command line, the system will prompt for the output 


filename (unless NOFILE is chosen). Next, it will prompt for the name of a 
catalog in the file manager system (SYSCATLG is a valid choice). 


GENINDX will search the catalog to generate the type of index specified in 


the command 


line. After processing the catalog, GENINDX will continue 


to prompt for additional catalogs until the user responds to the (#) prompt 
with a carriage return. 


COMMENTS 


EXAMPLE 


CROSSREF 
PURPOSE 


SYNTAX 


INPUT 


OUTPUT 
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General format of GENINDEX dialog. 


First, the command line is echoed on the COMDEV, along with time and 
date: 


GENINDX Indextype/Options Time Date 


Next, you are prompted for the output filename and the catalog to be 
searched: 


OUTPUT FILENAME: Filename 
# Catalog 


e If the SORT option is chosen, elaspsed time may be great (on the order 
of hours) for a very long index. 


e With the PSTAT option, status information is plated at regular inter- 
vals, informing user that system is still running. 


Sample GENINDX dialog: 


n> GENINDX SUBRS/UTIL ) 
OUTPUT FILE NAME:HELP.SUBRS ) 
#SYSCATLG ) 

# 

n> 


Lists object file entry points and external references. 


> CROSSREF ) 
+ FILESPEC 


FILESPEC Indicates object files to be cross-referenced: 


Catalog Name/File1, File2,xxxFilen 


To cross-reference various files in one catalog. 


Catalog Name//NLEV or Catalog Name 
To cross-reference the entire catalog of object files. 
For each file to be cross-referenced, CROSSREF Lists subroutines called, 


entry points and globals. CROSSREF will continue to prompt for additional 
catalogs until a carriage return is entered in response to the prompt. 
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EXAMPLE Sample CROSSREF dialog: 
n> CROSSREF 


# SYS.FM/FMSETDN 
CODE SIZE: 0040 DATA SIZE: 000A 


ENTRY POINTS: 
FMSETDN 


GLOBALS: 
TSKODATA TSKOLIST TSKERR 


SUBROUTINES: 
&SETUP &SETDWN MOV 


#) 


n> 


SYSTEM System references may be either symbolic or explicit. 
REFERENCES 


Symbolic References to Operating System (O/S) globals and subroutines may be 
References defined with the following commands for referencing loader INSERTs: 


For O/S level commands: 


INSERT JANMAKE.SYM.BASIC —_— (disc and memory areas) 
INSERT JANMAKE.SYM.SYS (resident system references) 
INSERT JANMAKE.SYM.SYSOV __ (system overlay references) 


And, if desired: 


INSERT JANMAKE.SYM.DBLINT (long integer utilities) 
INSERT JANMAKE.SYM.FLPT (floating point utilities) 
INSERT JANMAKE.SYM.FMSYS (file management references) 


Note 


SYMEFILEs will define these references more 
efficiently. There is also a standard SYMFILE 
for defining CADDS references. 


Explicit Avoid using explicitly defined references in a loader source file. Numeric 
References values and offsets are subject to change with each O/S revision. A loader 
| source file with explicit references may need modification to run on a re- 
vised O/S. To avoid this problem, use the symbolic references in the 

preceding INSERTs or the SYMFILEs listed below. 
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 Symfiles 


O/S REFERENCES 


CADDS 
REFERENCES 


EXECUTING 
APPLICATION 
CODE 


Symfiles define O/S references and CADDS references. 


References to O/S globals and subroutines may be defined with the 
following SYMFILEs. These SYMFILEs contain all the references from one 
or more system INSERT files. Only one SYMFILE may be used, and it must 
appear in a LOADSYM statement before any loader source file references 
are defined. The standard SYMFILEs and their contents are: 


SYMEFILE INSERT File References 
JANMAKE.SYMFILE.SYSFM | BASIC +SYS+FMSYS 
JANMAKE.SYMFILE.SYSFMLI BASIC +SYS+FMSYS+DBLINT . 
JANMAKE.SYMFILE.SYSOV BASIC +SYS+SYSOV 
JANMAKE.SYMFILE.SYSOVFM BASIC + SYS + SYSOV + FMSYS 
JANMAKE.SYMFILE.SYSOVFMLI BASIC +SYS + SYSOV + FMSYS 

| + DBLINT 
JANMAKE.SYMFILE.SYSOVFP BASIC + SYS + SYSOV + FLPT 
JANMAKE.SYMFILE.SYSOVFMLIFP BASIC + SYS + SYSOV + FLPT 
+FMSYS + DBLINT 
JANMAKE.SYMFILE.SYSOVFMFP BASIC +SYS+SYSOV +FMSYS 
+ FLPT 


To load system library routines, include LIB statements for 
LOADLIB.OSLIB and LOADLIB.FORTLIB in your loader source file. 


There is a standard SYMFILE for defining CADDs references: 
INSERT.SYMFILE.STANDARD 


Most application code is written to be executed within CADDS; this code 
is divided into two categories; bundled and unbundled. Bundled code and 
unbundled code differ in storage location and mode of access. 


e Bundled 


All bundled code is written to one disc file — CADDS.OVLY. 
CADDS.OVLY is made up of fixed-length blocks (overlays). Each 
overlay, created when a Make is processed, is written to a different 
offset in CADDS.OVLY. These overlays are referenced by ‘‘coreload 
numbers” that address a portion of the CADDS.OVLY file. Even 
within CADDS.OVLY, one overlay has no relationship to another 
except through references within code. 
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e Unbundled 


Each unbundled command is housed in its own disc file. For CADDS 
commands, these files are named CADDSAUX.Verb.Noun. Each 
unbundled CADDS command consists of one or more overlays in a 
CADDSAUxX disc file. These overlays are assigned negative coreload 
numbers. The first overlay ina CADDSAUX file is — 1, the second is 
—2, and so on. | | 


Referencing Code > 


Unbundled coreloads can reference all bundled coreloads. They can 
also reference other coreloads in their CADDSAUX file. They may 
not, however, reference other CADDSAUxX files, nor can bundled 
coreloads reference unbundled code. Since unbundled code cannot 
be referenced from outside its own file, utilities should not be written 
as unbundled code. 


Coremap | When a task is logged-in, it is allocated 32K words of address space, Of 
this space, 10K is shared and 22K is unique to the task. 


‘8000’x 
RESERVED 
| FOR 
| o/s | 
(READ ONLY) 


&CORTOP 


&ENTRY + &CLDCNT 


BASIC 


AVAILABLE | APPLICATION AVAILABLE 
LEVEL CORELOAD =| F COMMANDS 
(8K) 
COMMANDS 7 pone 
& COMMAND 
RESERVED 
FOR 
O/S 
O'x 
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Sample Bundled 
Makefile 


LL SERA SFES SAAS AAAS RHEE SS EES SRS SESS 


2!* 
3!****ABC.CLD9000.&BCD.CLD9001 
4\* 


BLAS RASS RES ESSS ASSES RS AA ASR eee 


6!* 
7ILOADSYM INSERT.SYMFILE.STANDARD 


Replaces the current loader symbol table with symbols defined in 
INSERT.SYMFILE.STANDARD. Use this insert to reference standard 
application symbols in every CADDS Make. 


SIEQU &MYCLD 01 


Sets the symbol &MYCLD equal to 01 (the last three digits of the 
coreload number converted to hex). 


9!* 
10!ICORORG &ENTRY 


Defines the lowest address in core where data will be written to. The 
symbol &ENTRY was given a value in: 
INSERT.SYMFILE.STANDARD. 


111* 
12IBLOCK &ENTRY,&ENTRY + &CLDCNT 


Symbolic definition of address areas 


13!* 
141LOAD ABC.CLX9000/CLX9001 
151LOAD (Your routines) 


16ILIB LOADLIB.CADDSLIB 
17!LIB LOADLIB.FORTLIB 
18!ILIB LOADLIB.OSLIB 


These LIB statements are used with CADDS 4 to reference load 
libraries containing standard routines. With CADDS 3, use the follow- 
ing load libraries instead: 


13) al tila aad lial delta 


17!LIB LOADLIB.FORTLIB (CADDS 3 Load Libraries) 
18!LIB LOADLIB.OSLIB3 


TO] HH HH eH ee ee ee ee 


20!FILENAME CADDS.OVLY 


All bundled code is written to the file CADDS.OVLY. 
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21IWRITE &MYCLD*NSCL + &DLB9,&ESICNT,&ESILOC,&CLDCNT,&ENTRY 


Tells the loader to write to a disc file, giving the location, the offset, 
and the starting core location 


e Executing Bundled Code 
To access the Makefile (O/S level), type: 
n>LOAD CLD9000.CLD9001/DEBUG = ABC ) 


DEBUG = ABC tells the loader to look for the ABC version. This should be 
used in the initial debugging phase to prevent the loader from writing to 
CADDS.OVLY. When the program is successfully loaded: 


Hexnum WORDS AVAILABLE IN BLOCK 


WRITE valt1,val2,...vals PERFORMED ON FILE 
CLD9000.CLD9001 7 


SYMBOL TABLE SAVED IN FILE 
CLD9000.&SYM.CLD9001hexnum 


is output. Next, enter CADDS: 


n>CADDS )} 
#SEL DEBUG DIR ABC ADD ABC//NLEV ) 


Sets up debugging overlays. To test the code: | 


¥TEST CLD 9001 ) 


1 [APATREREAEE EELS HELE REAR ERE TEASER ENE 
2!* 
3!1****ABC.CLDAUX.TRYONE.&BCD.CLDAO1 
4\* 

Hl CeESELLLA CAAA LAER ALAA PEAS AE EERE SSO R EHS 
6!* 

7ILOADSYM INSERT.SYMFILE.STANDARD 
8IEQU &MYCLD 00 


Sets the symbol &MTCLD equal to 00, meaning this is the first 
module in the file CADDSAUX. 


9!* 
10!ICORORG &ENTRY 
11!* 
12!IBLOCK &ENTRY,&ENTRY + &CLDCNT 
131* 
141LOAD ABC.CLXAUX.TRYONE/CLXAO1 


TRYONE is a verb-noun combination to describe the function of the 
routine. It should be unique to the catalog CLXAUX. 
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15!LOAD (Your routines) 
(Order not important) 


16!* 

17!LIB LOADLIB.CADDSLIB 
18!LIB LOADLIB.FORTLIB 
19!LIB LOADLIB.OSLIB 


With CADDS 4, these standard load libraries should always be 
specified in this order. For CADDS 3, use the following load libraries 
(order is important): 


1G] REE EREAS SCENES EERE ERAT ENTS 


17!LIB LOADLIB.FORTLIB (CADDS 3 Load Libraries) 
18!LIB LOADLIB.OSLIB3 


DS | a a Sl i ia i oR Halal 


20!* 
21!FILENAME CADDSAUX. TRYONE 
22!'WRITE &MYCLD*NSCL,&ESICNT,& ESILOC,&CLDCNT,&ENTRY 


Tells the loader to write to a disc file, giving the location, the offset, 
and the starting core location 


° Executing Unbundle Code 
At system level, type: 

n>LOAD ABC.CLDAUX.TRYONE.CLDAO1 ) 
The message: 

Hexnum WORDS AVAILABLE IN BLOCK | 


WRITE valt,val2,...valb PERFORMED ON FILE 
ABC.CLDAUX.TRYONE.CLDAO1 


SYMBOL TABLE SAVE IN FILE 
ABC.CLDAUX. TRYONE.&SYM.CLDAO1 


indicates success. To test the routine: 


n>CADDS } | 
#RUN PROG CADDSAUX.TRYONE ) 
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For O/S level commands, the basic coreload begins at COMMAND and 
extends to &CORTOP. (Refer to the coremap description elsewhere in this 
section.) O/S level commands should not be loaded with the DEBUG or 
OVCAT options of the loader. 


To execute an O/S level command: 
n>LOAD Overlayname ) 


where Overlayname is the name of the overlay containing the command 
and its affiliated routines. 


The message: 


Hexnum WORDS AVAILABLE IN BLOCK 


WRITE val1,val2,...val5 PERFORMED ON FILE 
Overlayname 


SYMBOL TABLE SAVED IN FILE 
Overlay.&SYM.name . 


indicates success. To execute the routine: 


n>CADDS ) | 
sRUN PROG CADDSAUX.TRYONE ) 


When the user enters a command at system level, command tables are 
searched in the following order: 


1. SYSUSERCMTBXXXxX (if activated by the USERCMTB command). 


2. SYSCMTB (is added to by the SYSCMTB or EDITCMTB 
command). 


3. The system command table. 
4. The SYSCOMMAND catalog is searched for an overlay file. 
5. The CVSCOMMAND catalog is searched for an overlay file. 


6. If the command string is a filename, the system will attempt to run 
the DD command with the file as input. 


7. If the DD command fails and the file is an overlay created with the 
loader CWRITE command, the system will attempt to RUN the 
command. 


A command listed in more than one COMMTAB is defined by the first 
entry found. 
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Sequence of Once a command definition has been located, the system begins executing 
Execution the command. Command execution follows this sequence: 


1. The memory command area is set to core constant (‘COF’x). 


2. There is a queue for tasks awaiting processing by the CPU. The task 
is initially assigned the highest allowable priority in this que. 


3. If core count is nonzero, core count words are read in from 
command disc location or overlay file into core location. 


4. \f the command is in an overlay file, that file will be closed. 
5. The system scan routines (INITCHAR, NXTCHAR) are set at the first 
nonblank character following the command name on the O/S 
command line. 
6. The system starts execution for the task at the starting address. 
Cross-Referenced The search for a cross-referenced command begins in the COMMTAB 


Command of the cross-referenced entry. 
Processing 


A command may not be defined by more than one level of cross- 
referencing. Therefore, all cross-referenced entries are ignored in the 


search for a cross-referenced command. 


The starting address for a cross-referenced command is incremented by 
the relative start location. 
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Section 3 
DEBUGGING 


The Subroutine Trace tool helps to isolate program bugs by allowing the 
user to monitor subroutine calls. As the program runs, calling and return- 
ing addresses of subroutines are displayed. Normal program execution is 
unaffected by the Subroutine Trace tool. 


The Subroutine Trace tool is closely related to the Application Debugger. 
These two features speed identification and correction of program pro- 
blem areas. When a task is run with the Debugger or Trace tool, one task 
worth of additional memory space is required. If user address space is full, 
one task must be logged out to run the Subroutine Trace or Debugger. 


Prefix an O/S level command line with the keyword TRACE. During ex- 
ecution of the object file, a ‘trace map” is output. This map indicates the 
calling and returning sequence for subroutines within a program. Each 
level of indentation on the trace map indicates a subroutine being called 
from within another subroutine. As the trace map is displayed, normal 
command output will be interspersed with trace output. 


A task that runs with the Trace tool or Application Debugger requires one 
task of additional memory. If the system has insufficient free memory, 
TRACE and DEBUG won't be enabled unless one task logs out. 


There are two ways to toggle trace output once the subroutine trace has 
been invoked: | 


e From the COMDEV, CTRL-T allows the user to start and stop trace 
output without affecting program execution. 


e Within a program, the System Overlay Routine SUBTRACE can be 
called with a literal argument of ON or OFF to toggle trace output on 
or off. A call to SUBTRACE.(‘OF’) at the beginning of the command 
will suppress trace output. If tracing is not enabled, a call to SUB- 
TRACE has no effect. To find trace status, use CHKTRACE. The 
function return will be either ‘ON’ or ‘OF’, to indicate whether the 
trace is on or off. 
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SYMBOLIC Unless the NOTRACE option is used, the loader will automatically save the 

REFERENCES symbol file for access by the Subroutine Trace tool and the Application 
Debugger. This enables the trace map to include symbolic entry point 
names alongside subroutine calling addresses. 


Symbol Symbol files from the TRACE or DEBUG options of the loader are stored 
Filenames by the file manager under the following naming conventions: 


e Symbol filenames are derived from the name associated with the 
loader keyword FILENAME. | 


¢ &SYM is inserted as the second to last level of the symbol filename. 
e Either VAL1 from the loader WRITE and OVWRITE commands, or 
0000 from the loader CWRITE command is ePReneer to the last level 
of the complete filename. 
EXAMPLES 


e Loader contains: 


FILENAME RENUM 
WRITE 00E9,0,0,2000,6000 


Symbol filename: 
&SYM.RENUMOOES 
e Loader contains: 


FILENAME SYSCOMMAND.COMPARE 
CWRITE 4000,2000,5000 


Symbol filename: 


SYSCOMMAND.&SYM.COMPAREO000 


Note 


See LOADER documentation for additional 
information. 
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Overlays Programs that are divided into memory overlays must be modified for 
tracing. This requires two new calls: 


e Instead of FREAD, use OREAD. 
e The Make file must use LIB LOADLIB.OSLIB. 


Neither of these changes will effect performance. 


Sample Output Commands Comments 

without Symbolic 

References LOAD MAKE.COMMAND.COMPARE/NOTRACE ! Load for command 
TRACE COMPARE TEST1,TEST2 ! Prefix TRACE to 


! command line 


CALLING TO 2000 ! Main routine 
CALLING TO 21F3 ! Call to a routine 
: ! loaded at 21F3 
| 


RETURN TO 200D Return to main routine 
CALLING TO 21F3 


RETURN TO 2016 


CALLING TO 27D2 ! Calls routine loaded 
at 27D2 
CALLING TO 2A42 ! Calls routine loaded 
at 2A42 
RETURN TO 27E5 ! Return to location 
27E5 
RETURN TO 2024 ! Return to main routine 


CALLING TO 27D2 
CALLING TO 2A42 
RETURN TO 27E5 

RETURN TO 2032 


Sample Output | Commands Comments 
with Symbolic | | 
References LOAD MAKE.COMMAND. COMPARE ! Load for command 


TRACE COMPARE TEST1,TEST2 | Prefix TRACE to 
| | command line 


CALLING TO 2000 COMPARE _ ! Main routine 
CALLING TO 21F3 | Internal subroutine 
RETURN TO 200D 
CALLING TO 21F3 | Internal subroutine 


RETURN TO 2016 
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Commands Comments 


CALLING TO 27D2 GETFIL 
CALLING TO 2A42 FMEXPNM 


RETURN TO 27E5 |! Return from FMEXPNM 
to GETFIL 
RETURN TO 2024 | Return from GETFIL 
CALLING TO 27D2 GETFIL ! to COMPARE 


CALLING TO 2A42 FMEXPNM 
RETURN TO 27E5 
RETURN TO 2032 


A debugger helps to isolate program bugs by allowing the user to monitor 
and change program execution. By setting breakpoints, the programmer 
can divide a program into segments and process one segment at a time. 
When a breakpoint ts reached, all processing halts. Values of program 
variables may be examined and reset at any breakpoint. 


The Application Debugger is closely related to another system feature, the 
Subroutine Trace tool. These two features speed identification and correc- 
tion of program problem areas. 


The debugger is invoked by prefixing any system command with 
the keyword DEBUG, this gets the user to debugger command level. On 
initial entrance, the debugger displays special notes as to command 
changes or new features. The prompt ‘‘DBG]” indicates that the debugger 
is at command level, ready to accept commands. 


The features included apply variously to syntax, toggles, following a break, 
and to local variables. 


e Syntax 


Terminate commands with a carriage return or a semicolon. The 
~ semicolon allows several commands to be strung together on one 
line. Most commands accept multiple arguments separated by 
commas and then process each argument or group of arguments 
individually. In this example: 


BS GETLINE,PUTLINE,GETCLOSE 


sets a breakpoint at the address of each subroutine name. 
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e Toggles 


CTRL T is used to enable and disable Subroutine Trace output. When 
a program is executing and the user would like to return to the de- 
bugger prompt, a CTRL D will force a break to debugger command 
level at the next subroutine entry or exit. 


e Following a Break 


After issuing debugger commands, the user may resume program 
execution with one of three commands: “BX” forces a break at the 
next subroutine entry or exit. P means proceed, or PN for proceed, 
not checking. P checks for subroutine breakpoints during program 
execution and returns to command level when one ts found. PN 
disables the debugger and continues normal execution; breakpoints 
are ignored. CTRL D will re-enable the debugger and return to de- 
bugger command level at any time. 


e Local Variables 


Local variables can only be accessed from the subroutine containing 
the current breakpoint. To examine a local variable, compile the 
subroutine using the TRACE option. If the routine was loaded with 
the NO TRACE option, reload. Then activate the full filename using 
the AF command (See Debugger Commands). Prefix local variable 
symbol names with a period. 


Restrictions Restrictions apply as indicated below. 
e Hexadecimal Numbers 
Use hex numbers to represent addresses and values. A hex number 
whose first digit is A-F must be preceded by a zero. For example, 
‘FFFF’x should be entered as ‘OFFFF’x. 


e Breakpoints 


Only breakpoints set at a subroutine entry or exit point will cause an 
actual break in program execution. 


e Address Space 
Breakpoints may not be set outside of application address space. 
System Resident Routines and System Overlay Routines are outside 


of application address space. Breaks may not be set within these 
routines. 
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¢ No-Wait I/O 
_ The Debugger automatically resets no-wait |/O to wait I/O. 


These commands apply to general control, toggles, and to breakpoints. 


P Proceed: Continues program execution, checking for break- 
points. 
PN ‘Proceed, not checking: Continues program execution without 


checking for breakpoints. 


BX Forces a break at next subroutine entry or exit point, regardless 
of whether a breakpoint was previously set. 


QUIT Returns the user to a system level prompt. 


H  —_—_—sCODiisplays debugger commands. 
? Same as H. 
; Used to separate commands. 


Both CTRL D and CTRL T act as toggles. 


CTRL D Forces a break to debugger command level at the next 
subroutine entry or exit point. 


CTRL T ON/OFF switch for subroutine tracing. 

Breaks will only be executed at subroutine entry points. 

LB Lists breakpoints. 
BAaddress1,address2... Sets breakpoints at address1,address2,... 


BS namet,namez... Sets breakpoints at entry points to subroutines 
name1,namez,... 


CA address1,address2.. Clears addresses from breakpoint list. 
CS name1,namez... Clears subroutine entries from breakpoint list. 


CL _ Clears all breakpoints from list. 
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Controlling the 
Execution of 
Breakpoints 


Dump Commands 


Setting Memory 


With the ‘‘count’’ and “‘reset’’ options, you can set the debugger to ex- 
ecute breaks at specified intervals. COUNT and RESET must be decimal 
integers. | 


BS namel1 [(count[,reset])], name2[(count!, reset])] eo 
BA address1[(count[,reset])],address2[(count[,reset])]... 


count An initial value that gets decremented each time the subroutine is 
called; at zero, a break will be be triggered. A value of zero or one 
means “‘break at every call’. 


reset Count is reset to this value after the first break to the debugger. 
The default for reset is zero. 


Several examples follow: 


BS FOO(5) Breaks at the fifth call to subroutine FOO and then every 
call after the fifth. 


BA 2345(3,3) Breaks on every third call to the subroutine at address 
2345. 


BS DBNEG(1,5) Breaks on the first call to DBNEG and every fifth call 
after the first. 


Three examples are described. 


D address, length Dumps memory, starting at address, for the 
specified length. 


D address1 > address2 Dumps memory from address! address2. 


DV name Dumps the contents of memory (addressed by 
a symbolic name). | 


Setting memory through the use of SA and SV. 


SA address = hex value 1, 
value 2...valuen Sets memory address to hex values. 


SV name = hex value 1, 


value 2...valuen Sets variable with specified name to 
hex values. 
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Searches for a hex value within the address bounds: 


SR value IN address, length. 
SR value IN address1 address2. 


AV name Returns address of variable. 
AC command1;command2 Initiates automatic command mode: This 
| string of commands will be executed at each 
- breakpoint. AC with no arguments resets 
the command. If looping occurs, CTRL D 
will force a return to the debugger prompt. 
Local variable names must be prefixed with a period. 


AF filename Filename is the routine’s full filename. Use 
the trace option for compiling the routine. 


PF | Print activated filename. 
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Section 4 


BRIEF SUBROUTINE DESCRIPTIONS 


LINKAGE FOR 
ROUTINES 


System Resident 
Routines 


System Overlay 
Routines 


System Library 
Routines | 


This section contains a brief description of subroutines and subroutine 
utility packages available to the application programmer. Each subroutine 
is described with a brief summary of its purpose. Subroutines are primarily 
grouped as to function, and secondarily, sorted alphabetically. More com- 
plete descriptions are listed alphabetically in Section 5. 


A reference to a system routine can be resolved by referencing one of 
three places in the operating system. To ensure complete linkage for your 
code, reference each of these places every time you load a program. 
Instead of explicitly loading a system routine, use the inserts and libraries 
mentioned below to resolve any references to the routine. 


Note 


User-written routines should be explicitly 
loaded in the Make. 


System Resident routines are permanently resident in core and available to 
all tasks. They are frequently used routines that often require access to 
system utilities. Several tasks may access a System Resident routine at the 
same time. System Resident routines are called explicitly or implicitly from 
within user code (for loader inserts, see Section 2). 


These routines are referenced in the ‘System Overlays (SYSOVLY). 
Overlay Routines are automatically read in from disc when not in memory. 


These routines are defined in the standard system inserts (see Section 2). 
These routines do not have to be explicitly loaded by the programmer. 
They do take up space in the user task area, however. Before terminating a 
block in the Make, specify: 


LIB LOADLIB.FORTLIB 
LIB LOADLIB.OSLIB 


or, for CADDS 3, 
LIB LOADLIB.OSLIB3 


These commands, included in this order, should resolve any unresolved 
references in the program. 
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ROUTINES 
LISTED BY 
FUNCTION 


File Manipulation 


File Utility 
Packages 


GETFILE 
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Changes to these routines will be reflected in the on-line documentation. 
To access on-line documentation from O/S level type: 


HELP SUBROUTINE 


HELP SYSROUTINE 


The following are low-level file manager routines. 


COPEN Opens a file for create or create with supersede. 
~MOPEN Opens a file for modification. 
ROPEN Opens a file for reading. 
FREAD _ Reads an open file. 
OREAD Reads an overlay into memory ( Used with Subroutine 
Trace and Application Debugger, See Section 3). 
FWRITE Writes to an open file. 
CLOSE Closes a file. 
DELETE Low-level FM routine to delete a file. 
CHKPROT Validates access rights to a file or command. 
CHKUPROT _ Verifies caller's default protection group for access to a file 
or command. 
RENAME General file manager utility routine. 
GETFILE Opens a text file for reading. 
GETLINE Reads the next line from a text file. 
GETLINEB _—_ Equivalent to GETLINE with a byte offset in the output. 
GETCLEAR Marks the file status block of an open text file to indicate 
that the buffer is no longer available. The next GETLINE 
call will do an FREAD. 
GETMARK Saves a position in a text file. 
GETPOS Restores a saved position within a text file. 
GETSTART Moves pointer to the beginning of a text file. 
GETCLOSE _ Closes a text file opened with GETFILE. 


PUTFILE 


READFILE 


WRITFILE 


READBFIL 
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Writing a text file. 


PUTFILE Opens a text file for output. 
PUTABORT  Aborts text file being written by PUTFILE. 
PUTLINE Writes a line to a text file. 


PUTLINEB Equivalent to PUTLINE with a byte offset. 


PUTCLEAR Marks the file status block of an open file to indicate that 
the text file buffer is no longer available. 


PUTCLOSE Closes a text file opened with PUTFILE. 


Used for reading words from a binary sequential file. 


READFILE Opens a sequential text file for reading. The standard 
sequence is to open with READFILE, read blocks of words 
with READBLOK, and close with READCLOS. 


READBLOK _ Reads the next block of words from a binary sequential 
file. 


READSECT Reads a block of words from a file opened for sequential 
word access. 


READMARK _ Returns the current position in a binary sequential file. 
READPOS Sets a new position in a binary sequential file. 
READTOP Moves pointer to beginning of a binary sequential file. 
READCLOS _ Closes a file opened with READFILE. 


Used primarily for writing words to a binary sequential file. 


MODIFILE Opens a binary sequential file for modification. 


WRITFILE Opens a binary sequential file for write. The standard 
sequence would be to create with WRITFILE, add blocks 
of words with WRITBLOK, and close with WRITCLOS. 


WRITBLOK — Writes a block of words into a binary sequential file. 


WRITCLOS Closes binary sequential file opened with MODIFILE or 
WRITFILE. 


Reads bytes or characters from a binary sequential file. 


READBFIL Opens a binary sequential file for byte-oriented input. 


READBYTE Retrieves the next block of bytes from a binary sequential 
file. 


READBCLS Closes the input channel of a binary sequential file opened 
with READBFIL. 
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Writes bytes or characters to a binary sequential file. 


WRITBFIL Opens a binary file, for writing with byte-oriented counts. 


-WRITBYTE Writes a record to a file opened by the routine WRITBEFIL. 


WRITBCLS _ Finishes writing and closes a binary file opened with 


WRITBFIL. 


There are two subroutine packages available for executing an FM catalog 
structure tree walk: CATWALK and TRAVERSE. 


Calls a user-defined subroutine to process nodes of a catalog. There are 
optional arguments for screening out various types of files, but processing 
of individual files remains under the control of CATWALK. 


Recovers, if CATWALK is interrupted. 


Processes selected nodes of a catalog with a user-defined 
subroutine. | 


CATWALK 


The TRAVERSE package processes a catalog by returning information 
about nodes and files. The actual processing of files is left to the discretion 
of the calling routine. 


TRAVERSE Initializes the TRAVERSE package by setting up the 

catalog to be traversed and the information to be returned 
| for each file. 7 

NEXTNODE _ Returns the next node or file to be processed by the calling 
routine. 

ABORTRAV Terminates the tree walk and “cleans up’ after error 
returns or after the entire catalog has been traversed. 

DELETEXT _ Deletes a text file. 

DELFIL Deletes a file and any empty catalogs above it. 


FMCNTRNM Removes the next to last level of a filename. 
Expands a filename by adding a level before the last level. 


System memory consists of 2K pages. Each page has a system memory 
page identifier (SPID). Users refer to a memory page by specifying its 
SPID. From the viewpoint of the application programmer, the SPID is a 
16-bit integer. 


ALLOCATION 


USER MEMORY 


PROTECTION 


Date and Time 


Task-Related 
Functions 
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The two allocation routines that follow permit the user to request memory 
pages for a task, or to return pages from the task to the system. The 
system limits the number of pages that a single task can own. Once they 
are allocated, however, the user becomes the owner of the pages. 


ALLOPG Allocates memory pages to user. 
FREEPG Returns memory pages to system. 


Each user has an address space of 32K words; this spaces is divided into 
sixteen 2K pages. The system manages a date structure called a ‘‘page 
frame” that describes which sixteen 2K pages are mapped to the 32K user 
address space. The two routines that follow permit the user to modify his 
page frame by either placing a page into, or removing a page from, any 2K 
page slot in his page frame. 


GETPG Returns system page ID and permission associated with a 
slot in the user’s page frame. 


SETPG Modifies a page slot of the user’s page frame. 


The user controls logical access to his pages. Protection access can be 
controlled with the following routines: 


GETPGP Reads the protection attributes of a page. 

SETPGP Modifies the parameters of a system page. 

CMPDAT Compares two dates (in system date and time format). 

FMIDAT Scans date (and time) from input stream, and converts 
| them to system date and time format. 

FMTDAT Converts a date from system date and time format (as 
: found in file entries) to printable format. 

GETDAT Returns the current date and time (system date and time 

format). 
TIME Returns the current date and time in a four-word array. 


GETTASK Gets the number of the current task. 
GETTASKF Calls GETTASK from a FORTRAN program 


HIBERN8 Deactivates task for specified time. 
CLEARCOM __ Fills the command buffer with blanks. 
SETSTRG Puts an eight-character string into the task message area. 
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ERROR _—- : “System ¢ error routine that returns control to the O/S. 


PER ROR | _ Prints an error message. from a message file when given an 
___ error number, then returns to the calling routine. 


RETERR a Bhatia 7 last system error number. 


jnchades dase Rincbene for wiectind the fealewiea: card reader, paper tape 
GEMICSS, and — epee drive. 


eo Task Functions 


"ATTACH | 


che a dpvice to a » task. 


UNATTACH Detaches a device from a task. 


CARDIN 


Card Reader 


Reads a card from CARDEV. 


e Paper Tape Devices oe 


CKPPTD _ 
-CKRPTD 


GETPPTD 

- GETPUNCH 
GETRPTD 
PNCHLDR 
PPT 
PPT1 
PPTN 
RPT 
RPT1 
RPTN 
SETPUNCH 


Checks idee. a oliniehi paper tape unit (PPTDEV) is 


assigned to a task. 


- Checks whether a read paper tape unit (RPTDEV) is 
assigned to a task. 


Attaches PPTDEV to a “a. 
_ Returns parity option of PPTDEV. 


_ Attaches RPTDEV to a task. 
Punches a leader on PPTDEV. 


Outputs words to PPTDEV. 

Outputs one character to PPTDEV. 
Outputs a string of bytes to PPTDEV. 
Inputs words from RPTDEV. 


Inputs one character from RPTDEV. 


Inputs bytes from RPTDEV. 
Sets the parity option for task PPTDEV. 


Subroutine 
Trace 


VALUES AND 
CHARACTERS 
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¢ Magnetic Tape Drive 


TAPE 


TAPENW 


TESTTAPE 
TREAD 


TREADNW 
TWRITE 
TWRITENW 


Processes a tape request according to keyword 
(KYWD). 


Processes a tape request according to ARGLST with 
the no-wait entry. 


Validates a tape unit task name. 


Reads a physical record from magnetic tape (unpacks 
if necessary). 


No-wait version of TREAD. 
Writes words on magnetic tape (unpacks if necessary). 


No-wait version of TWRITE; writes words on magnetic 
tape and returns I/O flag. 


These routines are used with the subroutine trace (see Section 3). 


SUBTRACE Toggles trace map output. 
CHKTRACE _ Gets status of trace map output. 


INITCHAR and NXTCHAR are automatically called to set up scanning of 
the command line. The two routines must be explicitly called to initialize 
scanning of any other stream of characters (I.e., a line input with TYPIN). 


Note 


All scan routines call ERROR when an error is 
detected. 


INITCHAR Sets up an array and character count for all system scan 
routines. 


NXTCHAR Gets the next character to be scanned, along with its type. 


DBHXNM Converts ASCII string to double precision integer. 

DBHXLST Scans a hex bounds list from the input stream. 

DBINT Scans a double precision decimal integer from the input 
stream. 


DBINTLST Scans a double precision integer list from the input 
stream. 
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HEXLST Scans hex bounds list from the input stream. 

HEXNUM > Scans a hex number from the input stream. 

IDENT Scans for an eight-BCD-character identifier from the input 
stream. 

INT Scans a decimal integer from the input stream. 

INTLST Scans a decimal bound list from the input stream. 

INITNM Initializes scanning of an FM NAME LIST. 

NXTNAM Gets next name from FM NAME LIST. 

FMIDNF Scans for a name (up to 20 characters) from the input 
stream (use with FORTRAN routines). 

FMIDNT Scans for a name (up to 20 characters) from the input 
stream (use with TPL routines). 

FMNAME Scans for a catalog name from the input stream. 

FMIDAT Scans date (and time) from input stream, and converts 


them to system date and time format. 


This section includes standard and no-wait |/O. 


TOGGLE Manipulates COMDEV and HARDEV toggles. 
STYPIN Functions like TYPIN, but uses options specified by the 
program. 
TYPIN Inputs a sequence of characters terminated by a carriage 
return from either the COMDEV or an execute file. 
STYPEOK Tests task COMDEV for “‘OK’’ response to specified 
, message. 
TYPEOK Tests for an ‘‘OK” response to a specified message. 
Response may come from task COMDEV or execute file. 
GLP Outputs line of characters to device. 
~ LP Outputs line of characters to COMDEV and the HARDEV. 
TYPE Outputs a line of characters, inserting a carriage return 
and a line feed at the end of the line. 
TYPEDBI Outputs double precision integer in decimal format. 
TYPEINT Outputs an integer in decimal format. 


NO-WAIT 
1/0 


Breaks and 
Labels 
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TYPOUT Outputs a line of characters without inserting carriage 
returns or line feeds. 

TYPEDBHX Outputs double precision integer in hexadecimal format. 

TYPEHEX Outputs an integer in hexadecimal format. © 

SRTESTIO Tests an IOFLAG for I/O completion and returns error 
numbers. 

TESTIO Tests an IOFLAG for !/O completion and calls system 
error handler when I/O errors are detected. 

SRWAITIO Changes a NOWAIT |/O request to a WAIT 1/O request 
and returns error numbers. 

WAITIO Changes a NOWAIT I/O request to a WAIT I/O request. 

CHKBREAK Checks whether CHKINTR, CHKQUIT, or CHKSTOP 
have detected a break. 

CHKINTR Checks for interrupt and waits or sets appropriate one- 
time switch in the task block. Handles all (ESC) 
characters. 

CHKQUIT Checks for interrupt (ESC) action based on next character 
input. Handles only Q, N, and K. 

CHKSTOP Checks for interrupt (ESC). If found, performs a quit. 

CLRBREAK Clears a task break flag. 

LBLGO Transfers control to task system label or statement label 
(see LBLSET). 

LBLSET Sets up a statement label or task system label for LBLGO 
transfer. 

SETBREAK Enables flag-setting for CHKBREAK and disables task 
inter-quit process. 

GETLABEL Accesses and saves a task system label. 

PUTLABEL Restores a task system label saved by GETLABEL. 

RESETLBL Restores a task system label to its original state. 
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Double Precision = This section discusses subroutines for manipulating and comparing double 
integers precision integers. 


e Addition and Subtraction 


ADJUST Increments a double word integer by a single word 
integer. 

DBADD Adds two double word integers. 

DBDCR Decrements a double precision integer. 

DBINC Increments a double precision integer. 

DBSUB Subtracts two double word integers. 


Division And Multiplication 


DBDIV Divides double precision integers. 

DIVUS Divides unsigned integers. 

DBMUL Multiplies unsigned single word integers, giving a 
double word integer. | 

DBNEG Reverses sign of double word integer. 

LABS Finds absolute value of a double integer. 


e Manipulation and Comparison 


DBMAX Finds the larger of two double integers. 

DBMIN Finds the smaller of two double integers. 

DBLSH Executes a double word left shift. 

DBRSH Executes a double word right shift. 

Comparison CMBYTF Compares bytes in two arrays (FORTRAN version). 

CMBYTT Compares bytes in two arrays (TPL version). 
COMPN Compares words in two arrays. 
COMPNAM ~— Compares two eight-BCD-character names. 
COMPUS Compares two unsigned integers. 
DBCMPR Compares two unsigned double integers. 


MAXIMUM Finds larger of two unsigned integers. 
MINIMUM Finds smaller of two unsigned integers. 
TSTZERO Tests if a double precision integer equals zero. 
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DBHEXBCD ~~ Converts double precision integer to text string using the 
hexadecimal radix. 


DBINTBCD Converts a signed double precision integer to BCD. 


DBLE Converts real to double precision real. 

DFLOAT Converts an integer to a double precision real. 
DFLOATL Converts a double integer to a double precision real. 
FLBCD Converts a floating point number to an ASCIl text string. 
FLOATL Converts a double integer to a real. 

HEXBCD Converts a hex word to BCD. 

IFIXD Converts a double-precision real to a single-word integer. 
INTBCD Converts an integer to a character string. 

ISNGL Converts a double integer to an integer. 

LFIX Converts a real to a double integer. 

LFIXD | Converts a double precision real to a double integer. 
OCTBCD Converts an integer to an octal text string. 

SNGL Converts double-precision real to real. 


The functions of filling an array, byte and character manipulation, and the 
moving of data between arrays are included. 


e Filling An Array 


FILL Fills a word array with a given value. 
FILLBYTT Fills a byte array with a given value. 
FILLCHRT Fills a character array. 

FILLDB Fills a double precision integer array with a given value. 
FILLF Fills a real array with a given value. 


e Bytes and Characters 


STBYTF Stores a byte (FORTRAN version). 
STBYTT Stores a byte. 

STCHRF Stores a character (FORTRAN version). 
STCHRT Stores a character. 

LDBYTF Loads bytes (FORTRAN version). 
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LDBYTT Loads bytes (TPL version). 
LDCHRF Loads characters (FORTRAN version) 
LDCHRT Loads characters (TPL version). 


e Moving Data Between Arrays 


MOV Moves integer data from one array to another. 

MOVB Moves integer data from one array to another, starting 
from the end of each array. 

MOVD Moves double precision real data from one array to 
another. 

MOVEWORD Moves a character string from one array to another. 

MOVF Moves real numbers from one array to another. 

MOVL Moves double precision integers from one array to 
another. 

MVBYTF Moves bytes (or characters) from one array to another 
(FORTRAN callable). 

MVBYTT Moves bytes (or characters) from one array to another 


(TPL callable). 


Stack IPDL Initializes a push-down list. 
Manipulation POP Pops a word off a push-down list. 
POPN Pops a block of words off a push-down list. 
PUSH Pushes a word onto a push-down list. 
PUSHN Pushes a block of words onto a push-down list. 
Bit Manipulation GETBIT Returns the value of a given bit. 
TSTBIT Returns the value of a given bit. 
PUTBIT Turns a bit ON or OFF. 
SETBIT Turns a bit ON. 
CLRBIT Turns a bit OFF. 
GETFLD Retrieves the value in a field and returns it as a right- 


justified integer. 
PUTFLD Puts a value into one field of a bit string. 


4-12 


Brief Subroutine Descriptions 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


Sorting Records Sort routines are divided into two categories; non-stable sorts and stable 
sorts. 


e Non-stable sorts (heap,shell) are generally faster, but they may change 
the original order of records with identical sort keys. 


e Stable sorts (straight insertion, selection) are generally slower, but they 
maintain the order of records with identical sort keys. 


HEAPSORT _ Sorts an internal file of single word records using a heap 
sort. 


INSESORT Sorts an internal file of single word records using a 
straight insertion sort. 


INSESRTN Sorts records using a straight insertion sort. 


SELESORT Sorts an internal file of single-word records using a selec- 
tion sort. 


SHELSRITN Sorts records using a shell sort. 


Miscellaneous GETSTAT Reads task or system statistics blocks. 
XEQTCOMM _ Executes a system command passed as a subroutine argu- 
ment. 
CHKSUM Computes CHECKSUM for an array. 


HEXDMP Debugging aid that dumps hex words from an array. 
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Section 5 
SUBROUTINES 


This section describes the conventions used and an alphabetic presenta- 
tion of subroutines. 


There are several headings for each subroutine description. The 
most common types are: SYNTAX, INPUT, OUTPUT, and FUNCTION 
RETURN. These headings have the following meanings: 


In relation to the calling code, the subroutines mentioned in this manual 
can be treated as either functions or external routines. 


To call an external routine: 
FORTRAN 
CALL Subroutinename (Arg1,Arg2,..Argn) 
TPL 
E:E Subroutinename.(Arg1,Arg2,..Argn) 
To call a function: 
FORTRAN 
Variable = Functionname(Arg1,Arg2,..Argn) 
TPL 
Variable = Functionname.(Arg1,Arg2,..Argn) 
TPL can call a function with no arguments but FORTRAN cannot. 
Arguments (Arg1,Arg2,..Argn) are mandatory to the function or 
subroutine call. The given call sequence is also mandatory, since the 


designation of arguments as either INPUT, OUTPUT, or both, cannot 
change. 
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Input 


Output 


Function 
Return 


UNIVERSAL 


Bit Numbering 


Array 
indexing 
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INPUT refers to arguments that accept values for processing by the 
routine. All routines treat input arguments as constants and output 
arguments as variables. If no input arguments are mentioned, the 
subroutine does not accept input. 


OUTPUT can assume one of two forms: 


e Subroutine arguments can receive values as output. These arguments 
are processed by the subroutine 


e Some subroutines output data to the COMDEV; this output may also be 
routed to a HARDEV or another device by setting the appropriate 
toggle. | 


OUTPUT should not be confused with FUNCTION RETURN. If no output 
arguments are specified, then the only way to pass values from the called 
subroutine to the calling routine is via the function return. Some 
arguments may be both INPUT and OUTPUT. 


If the routine is called as a function, then this value will be passed to the 
variable on the left side of the assignment statement within the calling 
code. In FORTRAN, it is important that Variable be of the same type (i.e., 
integer) as the function. 
For Example: 
TASKNUM = GETTASKF(INUM) 
Apply to all the routines in this manual. 
In system subroutines, bits are numbered from left to right, beginning at 
zero (See Section 6.) 
Note 
In CADDS application routines, bits are 


numbered from right to left. 


In this manual, array indices follow FORTRAN conventions. Indexing 
begins at one, rather than zero as in TPL. To convert indices to TPL, 
subtract one. 
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PARTICULAR 


FM Name 
Format 


Options 


File Status Block 


Apply to some, but not ail, routines. 


File or catalog names are generally passed to subroutines in in FM Name 
format, as follows (Word positions are in parentheses): 


Word Contents 


(1) Count of bytes in name 
(including delimiters and _ter- 
minating character). 


(2-n) Characters in name, terminated 
by an exclamation point (!), 
with a period (.) as delimiter 
between components. 


Routines with file manager entry points (ROPEN, COPEN, RENAME, etc.) 
DO NOT accept a byte count in Word 1 of the filename. 


Note 


No component of the name can exceed 20 
characters, and the entire name, including the 
(1), must not exceed 80 characters. 


OPTIONS refers to an array of one or more words. Some words may con- 
tain bit set flags; other full words or blocks of words may contain data. The 
exact format depends on the subroutine. In the syntax of this manual, 
words are enclosed in parentheses and bits are listed under the ‘‘bit’’ 
column heading (for more information, see SYSTEM FORMATS, Sec- 
tion 6). 


The File Status Block (FSB) is an array that displays the status of a file 
opened with one of the file utility packages (GETFILE, PUTFILE, READ- 
FILE, etc.). Whenever the file is accessed with a subroutine from the 
package the FSB is modified to appropriately reflect changes to the file. 


The GETFILE and PUTFILE utility packages, have an FSB of 8 words. For 
the READBFIL, WRITBFIL, READFILE, and WRITFILE utilities, FSB is 12 
words. In every package FSB(1) must be set to one when the file is 
opened. 


SUBROUTINES 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. , 


Note 
To avoid errors and ensure sequential file 


operations, preserve the integrity of the FSB. 


FILE This information applies to programming under the file management facil- 
MANAGEMENT ity on CGOS 200. 


e The following routines invoke the file management facility: 


CHKPROT CHKUPROT 


CLOSE COPEN 
DELETE FREAD 
FWRITE MOPEN 
RENAME ROPEN 


Link these routines using JANMAKE.SYM.FMSYS, or any SYMFILE that 
includes the references in JANMAKE.SYM.FMSYS (See Section 2). 


Note 


Avoid these low-level file management 
routines whenever possible. Instead, use the 
high-level file manipulation packages (see Sec- 
tion 4). 


e File management system calls follow standard FM file naming conven- 
tions except for one important difference. Word 1 of the filename 
should be the beginning of the characters in the name, not the byte 
count of the name. 


e A full file name cannot exceed 80 characters. The character count 
includes catalog levels, delimiters and the terminating exclamation 
point. | 


e All file management errors are in the hexadecimal range C000 to 
CFFF. (See SYSNEWS.ERROR.FM.) 


SUBROUTINE The following subroutines are listed in alphabetical order and described 
DESCRIPTIONS in some detail. 
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RETURN 


ADJUST 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the — 
express written consent of Computervision. 


ADJUST(DARGI,SARGI, DARGO) 
Increments a double word integer by a single integer. 


DARGI Double word integer addend. 
SARGI Single word integer addend. 


DARGO Double word integer sum. 


ALLOPG(SPID) 
Allocates memory pages. 
SPID System Page ID of the page allocated to the calling task. 


When a page is allocated, its logical protection attributes are initialized by 
calling SETPGP.(SPID,P&RW). 


0 No errors. 

E040 No page available — all system pages are allocated. 

E100 No page available — no more pages can be allocated to the 
calling task. 
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_ ATTACH(NAME, TYPE). 


Attaches a unit to a task. 


NAME Two character (one word) name assigned to the unit. 


TYPE One of the following: 


Four character (2 word) generic unit name. 
— 1 preceding a specific unit number. 

—2 (attaches the default HARDEV). 

—3 (attaches the first COMDEV) 


Either NAME is already in use, NAME is ‘CM’, or NAME is a bad 
type. 


No units of TYPE available. 
Attach successful. 


CARDIN 
SYNTAX 
PURPOSE 
INPUT 
OUTPUT 


FUNCTION 
RETURN 


COMMENTS 


ERRORS 
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CARDIN(MAX,ARR) 
Reads a card from the CARDEV. 


MAX Maximum number of characters to be moved into ARR. 


ARR Packed array of characters read from the card. 
— Card reader not ready. 

0 Read was successful. 
>0 Pick error or trouble. 


e Uses a ‘50’x word global named CARDBUF. 


e Unit characteristic words for the CARDEV determine whether card 
punches are translated into 029 or 026 character code. If the first unit 
characteristic word is zero (default condition), 029 characters will be 
returned. If the first word is non-zero, 026 characters will be returned. 


Section Two of the CGOS 200 Operator Guide contains a complete list 
of both card punch character sets. 


‘FOOE’x No CARDEV assigned. 
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CATBREAK(PDL) 


Resets CATWALK globals and closes open files when the execution of 
CATWALK has been interrupted. 


PDL Push-down stack used in the call to CATWALK. 


CATBREAK should never be called unless the execution of CATWALK has 
been interrupted. | | 


CATWALK 
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CATWALK(CATNAM,OPTIONS,SUBR,PDL,PDLSIZ, DATES) 

Calls a user-defined subroutine with the following syntax: 
SUBR(IND,NAME, ARRAY) 

Uses a user-defined subroutine (SUBR) to process selected nodes of a 
catalog. File-screening is optional. If IND = 2, the node has met file- 


screening criteria. 


CATNAM Catalog name, preceded by the character count and terminated 
by an exclamation mark (!). 


OPTIONS(1) 
Bit 
Number .— Status Function 
0-9 Zeroes 
10 ON Specifies method for selecting types 
of files from CATNAM to be pro- 
cessed by SUBR, as specified in 
OFF OPTIONS(3). 
11 ON Screen out files, except those 
before dates(3-4). 
12 ON Screen out files, except those since 
dates(1-2). 
13 ON Screen out temporary files on 
IND = 2 calls. 
14 ON Tree walk executed left to right, top 
| down. 
OFF Tree walk executed left to right, bot- 
tom up. 
15 ON Walk through ail levels. 
OFF Walk through one level only. 
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INPUT OPTIONS(2) 
(Continued) 
OPTIONS(1), BIT 10 OFF: 
= Q Includes all types. 
NEO Exclude files which do not meet the file-screening criteria, 
(i.e., IND #2); type N is specified by setting bit M in this word 
where M=15—N; type 1 means catalogs. 
OPTIONS(1), BIT 10 ON: 
= N Where N is the number of words (N ¥ 16) in the following bit 
array. The bit should equal the type of file to be processed by 
SUBR i.e., bit: 


0 ON FILE TYPE O 
1 ON FILE TYPE 1 


255 ON ~FILE TYPE 255. 


This bit array must follow immediately after the options input 
array. 


SUBR Subroutine to be called for each node. 


PDL Push-down stack to be used by CATWALK of size equal to 
maximum number of levels * 12. 


PDLSIZ Size of push-down stack. 
DATES System date and time format: 
(1-2) Since date and time — options bit 12 must be ON. 


(3-4) Before date and time = options bit 11 must be ON. 
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Calls SUBR in this format: 

CALL SUBR(IND,NAME,ARRAY) 
All arguments are given by CATWALK. SUBR is a user-defined routine 
that CATWALK invokes for each node in CATNAM. If IND = 2, the file has 


met screening criteria. 


It is the responsibility of SUBR to examine the value of IND and determine 
how the node will be processed. 


IND 
0: Start of CATWALK 


NAME: Dummy. 
ARRAY: Dummy. 


1: Node is “‘left parent’”’ (there are ‘‘child-nodes’’ beneath it in 
the catalog structure). 


NAME: Node name in the same form as CATNAM: zero 
implies SYSCATLG. 
Extended array from ROPEN for this node. 


2: Process this node 
NAME: Words 
(1-42) Node name. 
(43-45) Address in buffer for file ID. 
ARRAY: Catalog entry for node. 
3: Node ts right parent 


NAME: Node name. 
ARRAY: Dummy. 


—1: End of CATWALK 


NAME: Dummy. 
ARRAY: Dummy. 
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—2: Node is search catalog. Search not performed due to protection 
or modification. (Replaces 1 and 3 calls for node, and all calls in 
between.) | 


NAME: Node name. 
ARRAY: Catalog entry for node. 


0 Normal completion. 
‘COXX’x File management error, where XX represents two héx digits. 


A system overlay containing CATWALK may be loaded by user defined 
overlays. To use the CATWALK overlay: 


© The object code ‘LIB. CATWALK.LOADCATWALK’ must exist in the 
task file area. 


e The user overlay must begin at &FCTWKCM instead of &COMMAND 
(both are defined in the loader symbol file JANMAKE.SYM.BASIC). 


e The file ‘SYM.SYS.CATWALK’ must be inserted within the code sec- 
tion of the user overlay. | 


e Before any call to CATWALK, the user code must call ‘LDFCTWLK’ 
(see LIB.,CATWALK.LOADCATWALK) to load the CATWALK over- 
lay. The overlay need not be loaded explicitly. 


e The system CATWALK overlay also includes the following routines 
required by CATWALK: 


LIB.CMPDAT 

LIB.COMPARE 
LIB.DB/DBADD,DBCMPR,DBSUB,TSTZERO 
LIB.GETTASK 
UTIL.FM/BNDSCHK,SEPVOL,SQZSCT 


CHKBREAK 
SYNTAX 
PURPOSE 
FUNCTION 
RETURN 


NOTE 
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CHKBREAK 


CHKBREAK 


Checks whether a break has been detected by CHKINTR, CHKQUIT, or 


CHKSTOP since SETBREAK or CHKBREAK was called. 


0 No Break. 
1 Break detected. 


See SETBREAK. 
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CHKINTR 


~ Checks for interrupt (ESC) or (CTRL-B), and waits for the next character 
from the task information stream (TIS). | 


After the interrupt, CHKINTR reads the next character from the TIS and 
does one of the following: | 


Q «Performs a quit (see CHKSTOP). 


N Terminates any EXECUTE file in progress and performs a quit (see 
CHKSTOP). 


K Performs a quit and returns to O/S command level regardless of 
any previous LBLSETs. 


1 Prints one line and waits. 


2 Prints two lines and waits. 


9 Prints nine lines and waits. 
P Prints a page and waits. 


K Return to O/S. 


ON Terminates execute file and Quits. 
Q Quit. 
Other Character from TIS (byte format). 


All characters are cleared from the TIS when the interrupt is detected. 
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CHKPROT(PROTGP,ACTMASK) 


Validates access to a file or command, given a protection group and 
desired type of access. 


PROTGP Protection group to be validated. 
ACTMASK Integer mask indicating access: 


Bit (Leftmost bit is 0): 
0-7 Reserved. 


8 Model. 
9 Read. 
10 Write. 
11 Execute. 
12 Change. 
13 Delete. 
14 Reserved (must be zero). 


15 Type of match. 
ON Subset match of access. 
OFF Exact match of access 


0 Protection group valid for desired access. 
C012 Protection group invalid for desired access. 
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CHKQUIT 


Checks for interrupt (ESC) or (CTRL-B), and waits for the next character 
from the task information stream (TIS). 


Accesses the next character from the TIS. That character determines the 
action to be taken: 


Q Performs a quit (see CHKSTOP). 


N Terminates any EXECUTE file in progress and performs a 
quit (see CHKSTOP). 


K Performs a quit and returns to O/S command level 
regardless of any previous LBLSETs. 


0 No break detected. 

K Returns to O/S level. 

N Terminates execute file and performs a QUIT. 
0 Performs a QUIT. 


Other Character from TIS (byte format). 


CHKQUIT functions like CHKINTR, but only the characters Q, K, and N 
are valid for determining the action to be taken. 


CHKSTOP 
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CHKSTOP 


Searches for an interrupt key. If the search is successful, it performs a 
QUIT and clears the TIS. 


A QUIT does the following: 


e If the current command has called SETBREAK, it sets a flag in the 
task and returns. This flag may be tested by calling CHECKBREAK. 


e It calls LBLGO(INTRQUIT). 


CHKSUM(CNT, BUF) 
Calculates an additive checksum of words in an array. 


CNT Number of words. 
BUF Array. 
Total bit value of CNT words from the array BUF. 


CHKSUM does not check for an overflow 
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CHKTRACE(IDUMMY) 
Gets status of trace map output. 
IDUMMY Non-functional argument. 


Returns two characters: 


‘ON’ Trace printout is enabled. 
‘OF’ Trace printout is disabled. 
CHKUPROT(ACCESS) 


Verifies caller's default protection group for a specific type of file access. 
ACCESS Access mask for verifying protection: 


‘80’ BIT 8 Model 
‘40’ BIT 9 Read 
‘20’ BIT 10 Write 
‘10’ BIT 11 Execute . 
‘8’ BIT 12 Change 
‘4’ BIT 13 Delete | 
‘2’ BIT 14 Reserved: Must be zero 
‘1’ BIT 15 Type of match: 
0 = Exact match of access. 
1 = Subset match of access. 


0 User has desired access. 
‘C0Q12’X User lacks desired access. 
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CKPPTD(SWT) 
Checks for PPTDEV assigned to a task. 


SWT 0 Task has PPTDEV. 
—1 Task has no PPTDEV. 


CKRPTD(SWT) 
Checks for RPTDEV assigned to a task. 


SWT 0 Task has RPTDEV. 
—1 Task has no RPTDEV. 


CLEARCOM. 
Fills the command buffer with blanks. 
Command buffer blanked out. 


The command buffer is an 80-character Global called COMMAND located 
in SYSOVLY. 
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CLOSE(CHANNEL, OPTIONS, SPECIFR) 


Closes a file. Can also change file size or delete the file entirely. 


CHANNEL 
OPTIONS(1) 
Bit 
0 ON 
OFF 
1 ON 
2 ON 
3. ON 
4. ON 
5 ON 
6-12 
13. ON 
14 
15 ON 
OFF 


File channel number. 


(Leftmost bit is 0.) 
Bit 0 is ignored unless the file was opened for create. If 


opened for create, the file is deleted. The previous file 
will not be superseded. 


Normal. 


User attribute values are set to SPECIFR(1-2). Bit 1 is 
ignored if: 


e Channel was used to open file for short or regular 
read. 


e File was open for create with supersede and bit 0 is 
ON. 


Do not update access date. 


Change file size to value in SPECIFR(3-4). Ignored under 
same conditions as bit 1. 


Use creation date from SPECIFR(5-6). 


Set CHKSUM and filetype words as indicated in 
SPECIFR(7-8). 


Reserved (must be zero). 
OPTIONS(3) contains additional option data. 
Reserved (must be zero). 


Error FLAG will be returned as a function name in an 
error condition. 


ERROR.FLAG will be called in an error condition. 


INPUT 
(Continued) 


FUNCTION 
RETURN 


ERRORS 
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OPTIONS(3) 
Bit (Leftmost bit is 0.) 
0-15 | Reserved (must be zero). 
SPECIFR (Words) 
(1-2) New attribute value (if OPTIONS(1) bit 1 is on). 
(3-4) | New total sector count for file (if OPTIONS(1) bit 3 is on). 
(5-6) |New access date (if OPTIONS(1) bit 4 is set). 
(7-8) Set CHKSUM and filetype (if OPTIONS(1) bit 5 set). 
If OPTIONS(1) bit 15 is set: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


CLRBIT(STRING, INDEX) 
Turns off a specific bit in a bit string. 
STRING Bit string array. 


INDEX Index of the bit (leftmost bit is 0). 
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CLRBREAK 
Clears task break flag. 


Task break flag is set to interrupt the current task when CHKINTR detects 
an ESCAPE, a CTRL B or its equivalent (see SETBREAK). 


CMBYTFI(CNT,ARRAY1,N1,ARRAY2,N2) 

Compares bytes in two — (FORTRAN version). | 

CNT Byte count. 

ARRAY 1 First array to be compared. 

N1 Starting byte in first array (N1.GE.1). 

ARRAY2 Second array to be compared. 

N2 Starting byte in second array (N2.GE.1). 
| 0 The arrays are identical. 

(ARRAY1(M)— Location of the first 

ARRAY2(M)) bytes that differ. 


Byte indices start with 1. 
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CMBYTT(CNT,ARRAY1,N1,ARRAY2,N2) 
Compares bytes in two arrays (TPL version). 
CNT Byte count. 
ARRAY 1 First array to be compared. 
N1 Starting byte in first array (N1.GE.1). 
ARRAY2 Second array to be compared. 
N2 Starting byte in second array (N2.GE.1) 

QO The arrays are identical. 
(ARRAY1(M)- —_ Location of the first bytes that differ. 
ARRAY2(M)) 


Byte indices start with 0. 


CMPDAT(DATE1,DATE2) 
Compares two dates. 


DATE1 _ Two date-time arrays (system date 
DATE2 and time format) to be compared. 


QO Dates are the same. 


>0O DATE1 before DATE2. 
<Q DATE1 after DATEZ2. 
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COMPN(CNT,ARR1,ARR2) 
Compares words in two arrays. 
CNT Word count. 


ARR1 First array to be compared. 
ARR2 Second array to be compared. 


>0 ~—~ARR_71 is greater than ARR2. 
=0 Arrays are identical. 
<Q ARR’1 is less than ARR2. 


The comparison is arithmetic — words are treated as signed integers. 


a. 
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COMPNAM(NAM1,NAM2) 
Compares the ASCII values of two 8-BCD-character names. 


NAM1 First name (eight BCD chars). 
NAM2 Second name (eight BCD chars). 


=Q Names have equal ASCII values. 
>0 NAM‘1 is greater than NAM2. 
<0 NAM1 is less than NAM2. 


The two names are “‘alphabetized”’ in ASCli order. 


COMPUS(A,B) 


Compares two unsigned integers. 


A,B Unsigned (16-bit) integers. 
0 A equals B. 
1 A is greater than B. 

—1 A is less than B. 
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COPEN(CHANNEL, FILENAME, OPTIONS, SPECIFR,ARRAY) 


Opens a non-catalog file for create or create with supersede. 


FILENAME(1-41) 


Restrictions 


If open for create with supersede, file cannot 
be write protected, opened for modify, or 
opened for create. 


Full ASCII filename with a period (.) as the delimiter between components 
and an exclamation mark (!) following the last character. No component 
may exceed 20 characters. 


OPTIONS(1) 

Bit 

0 ON 
OFF 

1 ON 
OFF 

2 ON 
OFF 

3 ON 
OFF 


(Leftmost bit is 0.) 


Returns extended array. 


Returns normal array. 


Creates new file unless file exists (with bit 7 ON, new 
catalogs are created as needed). Generates an error if the 
file exists. 


Creates to supersede an existing file; new space will be 
allocated. An error is generated if the file does not exist. 


Allocates initial number of file sectors from SPECIFR(1-2) 
With bit 1 OFF, new file size is taken as original file size. 
With bit 1 ON, new file size is taken as task default size. 
Returns error code ‘CQ20’x as function name if con- 
tiguous sectors cannot be allocated. 


Allows non-contiguous sectors to be allocated, if 
necessary. 


INPUT 
(Continued) 


COPEN 
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11 


12 


13 


14 


ON 


OFF 


ON 


OFF 


ON 
OFF 


ON 
OFF 


ON 
OFF 


ON 


OFF 


ON 


OFF 


ON 
OFF 


ON 
OFF 


ON 


Approximate disc position is given in SPECIFR(3). This 
has precedence over bit 9 (next fit). 


Disc positioning of a new file is arbitrary or as per bit 9. 
Generate an EOF error if attempt to write will cause 


allocation of additional file space (may be over-written by 
FWRITE command option). 


Suppress EOF errors. 


File protection group is given in SPECIFR(4). 


Assign task default protection to the file. 


Create necessary new catalogs. 

Missing catalogs will generate an error (this bit is ignored 
if bit 1 is OFF). | 

Catalog protection group is given in SPECIFR(5). 
Assign task default protection to the catalog. 

Use next fit allocation strategy. Bit 4 has priority over bit 
9, 

Arbitrary or as per bit 4. 


File type is in SPECIFR(5). 
Assign type 0 to a newly created file. Under create with 
supersede, retain the original file type. 


Reserved (must be zero). 


If Directories are enabled, use local create catalog. 


If directories are enabled, use global create catalog. 


OPTIONS(2) contains additional option data. 
Ignore OPTIONS(2). 


Return working directory name count in OPTIONS(3) 
followed by characters named in OPTIONS (4-42). If no 
working directory is enabled, value is returned in 


~ OPTIONS(3). 


5-27 


COPEN 


The information and drawings contained herein are the sole property of Computervision 

Corporation. Use of this document is reserved exclusively for Computervision customers 

and personnel. Reproduction of this matter in whole or in part is forbidden without the 
_express written consent of Computervision. 


INPUT 15 ON Error condition results in error FLAG returned as function 
(Continued) name. 


OFF _ Error condition results in the call ERROR(FLAG). 


OPTIONS (2) 
Bit (Leftmost bit is 0.) 
0-15 Reserved (must be zero). 


SPECIFR (Word) 


(1-2) Total sector count of the new file (unless OPTIONS(1) bit 2 is 
OFF). 


(3) Approximate position on logical file unit (unless OPTIONS(1) bit 
4 is OFF). Position is calculated in 1/32s of a file unit. 


(4) File protection group (word 13 of file entry — ignored if 
~ OPTIONS(1) bit 6 is OFF). 


(5) Catalog protection group (ignored if OPTIONS(1) bit 8 is off). 
(6) File type (ignored if OPTIONS(1) bit 10 is OFF). 
OUTPUT ; OPTIONS(1) bit 14 ON: 


OPTIONS(3) Directory name character count < if working direc- 
tory not enabled). 


OPTIONS(4-42) Directory name for OPTIONS(3) number of 
characters. 


ARRAY File information array. 
OPTIONS(1) bit 0 OFF: 
(Words) Normal Array. 
(1-2) Disc location always (0,0). 


(3-4) Total sector count of file. | 
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OPTIONS(1) bit 0 ON: 


(Words) Extended Array. 
(1-2) Disc location always (0,0). 
(3-4) Total sector count of file. 
(5) Creation date. 
(6) Time of day created (1 second intervals). 
(7) Access date. 
(8) File protection group. 
(9) File status, when bits are ON: 
Bit (Leftmost bit is 0.) 
0 In use. 


Opened for modify in place. 


2 To be deleted when closed if use count is 0 
(i.e., old file of create with supersede). 

3 Open for create. 
This entry is a temporary one for create with 
supersede. 

5 Opened for regular read. 

6 Reserved. 

7 File is a catalog. 

8-15 Reserved. 

(10) Number of users currently accessing file or 


included file, incremented each time the file 
or included file is opened, decremented 
each time it is closed. 
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(11) 


Bit 
0-7 = 
>0 


8-15 


DWPOMIYNOnAWNH-O 


C-E 


Contiguous data flag 0 All data allocated 
contiguously 


Data not contiguous, N is sector count (N 
0) of first contiguous chunk of the file (if file 
has QO length this is indicated by 
ARRAY (3-4)). 


User defined attribute value. 
User defined attribute value. 
CHECKSUM. 


File type 

(Leftmost bit is 0.) 

Not task protected. 

1 + number of task which has protected 
the file. 


Not defined. 

Catalog. 

Object. 

Text. 

Configuration. 
Reserved. 

PEP object code. 

Core image (overlay). 
Command table. 

Loader data file (symbol table or library). 
Reserved. 

Accounting table. 
Reserved. 

Z80 binary files. 
Reserved for CGOS. 
CADDS 4 part files. 
CADDS 4 TVF files. 
CADDS 4 figure files. 
Reserved for CADDS 4. 
Unused. 

Reserved for batch files. 
Unused. 

Work files (deleted on FMCLEAR). 
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ERRORS 
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CHANNEL Channel number assigned to file. 


OPTIONS(1) bit 15 ON: 


0 


FLAG 


Indicates no error. 
Indicates type of FILE MANAGER ERROR. 


For description of FILE MANAGER ERRORS, refer to SYSNEWS. 


ERROR.FM. 


COPYFILE(FTYPE,-FCOPY,BUFSIZ, BUF,NAME1,NAME2) 


Copies an FM file. 


FTYPE 


FCOPY 


BUFSIZ 


BUF 
NAME1 


NAME2 


PmWNH- oOo 


tH 


0 Copy any file (other than a catalog). 
0 Copy only files of type ‘““FTYPE”’. 


0 Overwrite if file exists. 
0 Ask user if file exists. 
0 Calls ERROR if file exists. 


Buffer size in words — must be at least SECTSIZ (usually 
256) words long. | 


File copy buffer area. 

Name of FM source file. 

Name of FM destination file. 
Buffer is too small to copy names. 
Copy succeeded. 

No channel available. 

File is a catalog. 


Improper type of file. 
File already exists. 
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DBADD 
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OUTPUT 
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DBADD(ARG1,ARG2,ARG3). 


Adds two double word integers. 


ARG1,ARG2 Double word addends. 


ARG3 


Double word sum. 


DBCMPRI(A,B). 


Compares two unsigned double precision integers. 


A,B 


Two double precision numbers. 


A is greater than B. 
A equals B. 
A is less than B. 


DBDCR 
SYNTAX 

~ PURPOSE 
INPUT 


OUTPUT 


DBDIV 
SYNTAX 
PURPOSE 


INPUT 


OUTPUT 


FUNCTION 
RETURN 


COMMENT 
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DBDCR(ARG) 
Subtracts one from a double precision integer. 
ARG Double precision integer. 


ARG Decremented double precision integer. 


DBDIV(DIVIDEND, DIVISOR, REMAINDER). 

Divides a double precision integer by a single precision integer. 
DIVIDEND Double precision integer (unsigned). 

DIVISOR Single precision integer (unsigned). 
REMAINDER _ Single precision remainder (unsigned). 


Single precision quotient (unsigned). 


Carry is set if quotient is greater than ‘FFFF’x. 
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DBHEXLST(LIST) 


Scans a hex bounds list from the input stream. 


LIST Double word integer array containing: 
(1) Count of numbers in list (all hex integers). 
(2) XXXX]q 
(3) YYYY 4 (or XXXXq1 , if YYYY4 omitted) 


(n*2)  XXXXpy 
(n*2+1) YYYYp, (or XXXXp , if YYYYp7 omitted) 


The text being scanned has the form: 


XXXXq (-YYYY4) ,-22.XXXXmq (-YYYY py } 


INITCHAR and NXTCHAR set up BCD string and system overlay globals 
for DBHEXLST. The two routines are automatically called to set up 
scanning of the command line. They must be explicitly called to initialize 
scanning of any other stream of characters (i.e., a line input with 
TYPIN). 


DBHEXLST will push past blank characters upon termination. 


See HEXLST, INTLST, and HEXNUM. 


DBHEXBCD 
SYNTAX 


PURPOSE 


INPUT 


OUTPUT 


DBHXNM 
SYNTAX 
PURPOSE 


INPUT 


OUTPUT 


COMMENTS 
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DBHEXBCD(HEX,BCD) 


Converts a double precision integer to a text string using the hexidecimal 
radix. 


HEX Double precision integer to be converted. 


BCD Four-word array (eight characters) containing the converted text 
string. 


DBHXNM(STRING, HEXVAL) 

Converts an ASCII string to a double word hex integer. 

STRING May include 0 through 9 and A through F, with a maximum 
of 8 characters. CHAR, a system overlay global, contains the 
first ASCII character. Its type is in CHARTYP. 

HEXVAL Two-word hex integer result. . 

e INITCHAR and NXTCHAR set up the BCD string and system overlay 
globals for DBHXNUM. The two routines are automatically called to 
scan the command line. When any other string of characters is scanned, 
they must be explicitly called. 

¢ DBHXNM will push past trailing blanks. 


e Routines LIB.DBLSH and LIB.DBADD must be loaded. 
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DBINC(ARG) 


Adds one to a double precision integer. 


ARG Double precision integer. 
ARG Incremented double precision integer. 
DBINT(RESULT) 


Scans the input stream for a double precision decimal integer. 
RESULT Positive double precision integer. 


e INITCHAR and NXTCHAR set up the BCD string and system overlay 
globals for DBINT. The two routines are automatically called to scan the 
command line. When any other string of characters is scanned, they 
must be explicitly called. 


DBINT will push past trailing blanks on termination. 


DBINTBCD 
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DBINTBCD 
SYNTAX DBINTBCD(DBNUM,BCD,COUNT) 
PURPOSE Converts a signed double precision integer to a character string. 
INPUT | DBNUM _ Signed double precision integer. 
OUTPUT BCD BCD character string. 
COUNT Length of the string (COUNT <11). 

COMMENT Character string Is left-justified in a BCD array. 
DBINTLST 
SYNTAX DBINTLST(LIST,MAX) 
PURPOSE Scans the input stream for a list of double precision integers. 
INPUT MAX Maximum allowable value of LIST (1) 

(MAX <4). 
OUTPUT LIST Bounds list in form: 

(1) Number of words in LIST following. 

(2-3) Double precision integer X1. 

(4-5) Double precision integer Y1 (or X1 if Y1 was omitted in 

input stream). 

COMMENTS 1. The text string being scanned has the form: 


X1(-Y1),..., Xn(-Yn ) 

2. INITCHAR and NXTCHAR set up character string and system globals 
for DBINTLST. The two routines are automatically called to scan the 
command line. When any other stream of characters is scanned, they 
must be explicitly called. 


3. DBINTLST will push past trailing blanks on termination. 


5-37 


DBLE 


DBLE 
SYNTAX 
PURPOSE 
INPUT 


FUNCTION 
RETURN 


DBLSH 
SYNTAX 
PURPOSE 


INPUT 


OUTPUT 
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DBLE(F) 
Converts real to double precision real. 
F Single precision real. 


Double precision real. 


DBLSH(ARG1,ARG2,ARG3) 
Does a double word left shift. 


ARG1(1-2) Double word value to be shifted. Zeros will be shifted into 
low order bits. | 


ARG2 Shift count 0-31. If 0 or negative, no shift is performed and 
ARG3 = ARGI1. 


ARG3(1-2) Double word shifted result. 


DBMAX 


SYNTAX 


PURPOSE 
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OUTPUT 


SYNTAX 


PURPOSE 
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OUTPUT 
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DBMAX(NUM1,NUM2,MAX) 
Finds the larger of two double integers. 


-NUM1 First double integer to be tested. 
NUM2 = Second double integer to be tested. 


MAX Either NUM1 or NUM2, depending on which is larger. 


DBMIN(NUM1,NUM2,MIN) 
Finds the smaller of two double integers. 


NUM1 First double integer to be tested. 
NUM2 Second double integer to be tested. 


MIN Either NUM1 or NUM2. 
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DBMUL 

SYNTAX DBMUL(ARG1,ARG2, ANSWER) 

PURPOSE Multiplies unsigned single word integers, giving double word integer 
result. 

INPUT ARG! Single word integer (Multiplier). 
ARG2 Single word integer (Multiplicand). 

OUTPUT ANSWER Double word integer. 

DBNEG 

SYNTAX DBNEG(ARG) 

PURPOSE Uses two’s complement arithmetic to reverse the sign of a double preci- 
sion integer. | 

INPUT ARG Signed double precision integer. 

OUTPUT ARG Two’s complement of INPUT argument. 


DBRSH 
SYNTAX 
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OUTPUT 
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DBRSH(ARG1,ARG2,ARG3) 
Executes a double word right shift. 


ARG1(1-2) Double word value to be shifted. Zeros will be shifted into 
high order bits. 


ARG2 Shift count 0-31. If 0 or negative, no shift is performed and 
ARG3 = ARGI1. 


ARG3(1-2) Double word shifted result. 


DBSUB(ARG1,ARG2,ARG3) 
Subtracts two double word integers. 
ARG2 To be subtracted from ARG1. 


ARG3 Double word difference, ARG1-ARG2. 


5-41 


DELETE 


DELETE 
SYNTAX 
PURPOSE 


INPUT 


OUTPUT 


5-42 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


DELETE(FILENAME, OPTIONS) 
Deletes an unused file or catalog. 


FILENAME Full ASCII filename with a period as the delimiter between 
components and an exclamation mark following the last 
character. Each component of the filename must be 20 
characters or less. 


OPTIONS(1) 
Bit (Leftmost bit is 0.) 
0-12 Reserved (must be zero). 


13 ON OPTIONS(2) contains additional option data. 
OFF OPTIONS(2) ignored. 

14 ON Return working directory name count in OPTIONS(3), 
followed by name characters in OPTIONS (4-42). Unless 
a working directory is enabled, value is returned in 

~ OPTIONS(3). 
15 ON Error FLAG returned as function name. 
| OFF _ Error condition results in the call ERROR(FLAG). 


OPTIONS (2) 
Bit (Leftmost bit is 0.) 
0-15 Reserved (must be zero) 


OPTIONS(1) bit 14 ON: 


OPTIONS(3) Directory name character count <0 if working direc- 
tory not enabled). 


OPTIONS(4-42) Directory name for OPTIONS(3) number of chars. 


FUNCTION 
RETURN 


ERRORS 


NOTE 


DELETEXT 


SYNTAX 


PURPOSE 


INPUT 


FUNCTION 
RETURN 
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OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


For description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


Catalogs and files which are write or access protected cannot be deleted. 


DELETEXT(FNAME) 
Deletes a text file. 
FNAME Filename in FMNAME format: 


Word 1 Count of bytes in name (including !). 
Word 2-N__ Filename (includes ! but does not include &BCD). 


0 Successful. 
Other File manager error number. 


DELFIL 


DELFIL 
SYNTAX 


PURPOSE 


INPUT 


FUNCTION 
RETURN 


DFLOAT 
SYNTAX 
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FUNCTION 
RETURN 
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DELFIL(FILENAME, OPTIONS) 


Deletes the last catalog level or file specified in the filename. Also deletes 
any previous catalog levels, provided they contain no other catalogs or 
files. 


FILENAME(1-41) | 

Full filename character string with a period (.) as delimiter between com- 
ponents and an exclamation mark (!) following the last character. Each 
component of the name must be 20 characters or less. 

OPTIONS(1) 


Bit (Leftmost bit is 0.) 


0 ON Print all deleted files. 
OFF Do not print deleted files. 


15. ON If specified catalog level and/or file not found return an 
‘C055’x or ‘CO06’x error. 


OFF _ If the catalog level or file specified in FILENAME does not 
exist, then delete all previous catalog levels that contain 
no subcatalogs or files. 

<0 FM Error. If file not found, then either ‘COO6’x or ‘C005’x 


error is returned. A ‘CQ17’x error is returned if the file is in use. 
=(Q No errors. 


DFLOAT(I) 
Converts an integer to a double precision real. 
i Integer. 


Double precision real. 


DFLOATL 


SYNTAX 
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FUNCTION 
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DFLOATLI(L) 
Converts a double integer to a double precision real. 
L Double integer. 


Double precision real. 


DIVUS(A,B) 

Divides unsigned integers. 

A Unsigned integer dividend. 
B Unsigned integer divisor. 


Unsigned integer result (A/B). 
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ELAPTIME 
SYNTAX ELAPTIME(ARR,RARR) 
PURPOSE Calculates elapsed time. 
INPUT ARR Base time: 
0 — Year (right two digits). 
1 — Day of year (starting at one). 
2 — Minutes of day. 
3 — Tenths of seconds. 
OUTPUT RARR Elapsed time since base time 
OQ — Year (right two digits). 
1 — Day of Year. 
2 — Minutes of day. 
3 — Tenths of seconds. 
FUNCTION 1 Elapsed time is positive. 
RETURN — Elapsed time is negative. 


ERROR 
SYNTAX 
PURPOSE 
INPUT 


OUTPUT 


NOTE 


ERROR 
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ERROR(VAL) 
System error routine. 
VAL Four-digit hex value. 


Based on the type of error call, ERROR will store information in various 
memory locations (hex values): 


Absolute 
Location Contents 


18 Memory violation address for: ‘FF04’x and ‘FFO5’x. 


19 Error code for ‘FFO1’x. PC at time of memory violation for: 
‘FFO4’x through ‘FFO7’x. 


1A Error Flag Meaning 


‘FFO1’x Error. 

“FFO2'x Undefined subroutine. 

“FFO3'x Wild jump. 

"FFO4'x Write violation: Attempt to write read-protected 


memory. 
“FFOD'x Access violation: Attempt to read or write access 
protected memory. 
“FFO6’x Instruction violation: Attempt to disable map from 
task space. 
“FFOQ7’x Defer violation: Ninth level of indirection exceeded. 
1B Roll table pointer at error call. 


1C,1D 
1E,1F ACO0,AC1,AC2,AC3 at error call. 


When ERROR is called, its argument, error cause flag, roll table pointer, 
and index registers are saved. If SYSERLBL has been set and it has 
positive value, a LBLGO(SYSERLBL) is executed. Otherwise, control is 
returned to the system. 
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FILL(CNT, VALUE, ARR) 


Fills an integer array with a given value. 


CNT 
VALUE 
ARR 


ARR 


Count of words to fill. 
The given value to fill them with. 
The array to fill. 


The filled array. 


FILLBYTT(CNT,VALUE,ARRAY,N) 


Inserts a given value into each slot of a byte array. 


CNT 


ARRAY 


Count of bytes to fill. 
Word containing byte, in byte format. 
The byte array to fill. 
First byte position to be filled (N=O). 


Full byte array. 


Byte indices start at 0. 


FILLCHRT 


SYNTAX 


PURPOSE 


INPUT 


OUTPUT 


COMMENT 
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FILLCHRT(CNT, VALUE, ARRAY,N) 
Inserts a given value into each slot of a character array. 


CNT Count of bytes to fill. 

VALUE Word containing character, in character format. 
ARRAY _ The character array to fill. 

N First character position to be filled (N=O). 


ARRAY __ The filled character array. 


Byte indices start at 0. 


FILLDB(CNT, VALUE, ARRAY) 
Inserts a double precision integer into each slot of an array. 


CNT Number of integers to insert. 
VALUE Double integer value inserted. 


ARRAY _ Double integer array filled with COUNT double integer values. 


FILLF 


FILLF 
SYNTAX 
PURPOSE 


INPUT 


OUTPUT 
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FILLF(CNT, VALUE, ARRAY) 

Inserts a real value into each slot of an array. 
CNT Number of real numbers to insert. 
VALUE _ Real value to insert in array. 


ARRAY _ Real array filled with numbers. 


FLBCD (FLT, BCD) 
Converts a floating point number to BCD characters. 
FLT Floating point number. 
BCD Six-word array containing: 
(1) Number of BCD characters in the result. 
(2-6) Left-justified string of BCD characters. There are a 


maximum of three positions to the right of the decimal 
point. 


FLOATL 
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FLOATLI(L) 
Converts double integer to real. 
L Double integer. 


Real. 


FMCNTRNM(OLDNAME,NEWNAME) 
Removes the second-to-last level of a file management filename. 


OLDNAME Original filename in format: 
(1) |Number of characters including an exclamation 
mark(!). 
(2-N) Characters in filename, terminated by a period (.). 
NEWNAME Contracted filename in same format as OLDNAME. 


QO Name contracted. 
—1 Name too short to contract. 
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FMEXPNM(OLDNAME, ADDNAME,NEWNAME) 


Inserts an additional catalog name as the next to last level of the file 
management filename. 


OLDNAME 
(1) 

(2-N) 
ADDNAME 


(1) 
(2-N) 


NEWNAME 


Original filename in format: 

Number of characters including a period (.). | 
Characters in filename terminated by an exclamation mark 
(1) (two characters/word). 

Level to be added in format: 

Number of characters in level (without punctuation) 
Characters in level (without punctuation — two 
characters/word). ) 


Resultant filename in same format as OLDNAME. 
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FMIDAT(DATIM) 


Scans date (and time) from input stream, where date (and time) are in the 
following format: 


MM-DD-YY (:HH:MM:SS) 
and converts to system date and time format. 
DATIM Two-word date and time array. 


0 Date and time correct. 
— Bad date and time. 


e INITCHAR and NXTCHAR set up the BCD string and system overlay 
globals for FMIDAT. The two routines are automaticlly called to scan — 
the command line. When any other string of characters is scanned, they © 
must be explicitly called. 


e FMIDAT will push past blank characters after completing the scan. 


e See also, FMTDAT, GETDAT. 
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FMIDNF(SUB,LIST,CNT) 


Scans a name (up to 20 characters) from the input stream (FORTRAN 
version). | 


SUB Byte position at which name storage is to begin in array 


LIST(SUB =>1). 


LIST Name that has been scanned off. 


INITCHAR and NXTCHAR set up the BCD string and system overlay 
globals for DBHXNUM. The two routines are automatically called to 
scan the command line. When any other string of characters is scanned, 
they must be explicitly called. 
The name scan will terminate on any of the following characters: 

, / Blank ! \~ A Rubout 
FMIDNEF will push past trailing blanks on termination. 


Byte indices start at 1. _ 


This routine intended for use with FORTRAN routines. 
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FMIDNT(SUB,LIST, CNT) 
Scans a name (up to 20 characters) from the input stream. 


SUB Byte position at which name storage is to begin in array LIST 
(SUB =0). 


LIST Name that has been scanned off. 

e INITCHAR and NXTCHAR must be called to set up the string scan. The 
two routines are automatically called to set up scanning of the command 
line. They must be explicitly called to initialize scanning of any other 
stream of characters (i.e., a line input with TYPIN). 

e The name scan will terminate on any of the following characters: 

, / Blank ! [] \ A Rubout 
e FMIDNT will push past trailing blanks on termination. 


e Byte indices start at 0. 


e This routine is intended for use with TPL routines. 
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FMNAME(LIST) 
Scans a catalog name from the input stream. 
LIST Catalog name as follows: 


Word 1 Number of bytes in name (including “!"). 
Word 2-n Catalog name with a period(.) between each 
component and a “’!’’ following the last character. 


INITCHAR and NXTCHAR initialize the scan for FMNAME. The two 
routines are automatically called to scan the command line. They must be 
explicitly called to initialize scanning of any other stream of characters 
(i.e., a line input with TYPIN). 


FMNLST(LIST) 


Scans the input stream for a list of comma-separated names. The list is 
defined by FMIDNT. 


LIST List of names in the following format: 


Word 1 Number of names. 


Word 2-n M-+1 bytes for each name as follows: 


Byte 0: Number of characters in name. 
Bytes: Characters in name. 


ITCHAR and NXTCHAR initialize the scan for FANLST. When the com- 
mand line is scanned, the two routines are automatically called. They 
must be explicitly called to initialize scanning of any other stream of 
characters (i.e., a line input with TYPIN). 


e FMNLST is part of a package that includes INITNM and NXTNAM. Call 
FMNLST to get the list of names, and then call INITNM and NXTAM to 
get individual names from the list. 


FMTDAT 
SYNTAX 


PURPOSE 


INPUT 


OUTPUT 


NOTE 


FMTDAT 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 


express written consent of Computervision. 


FMTDAT(INSWT,ARRAY,DATE, TIME) 


Converts a date from system date and time format (as found in file entries) 


to printable format. 


INSWT Bit 
14. ON 

OFF 
15 ON 

OFF 


ARRAY (1) Bit 
0 
1-6 
7-10 
11-15 


ARRAY(2) Time: 


(Leftmost bit is 0.) 


Convert seconds (if bit 15 is on). 
Do not convert seconds. 


Convert time. 
Do not convert time. 


(Leftmost bit is 0.) 


AM/PM indicator: ON for PM, OFF for 
AM. 

Number of years since 1960 (0 to 63). 
Month = (1-12). 

Day (1-31). 


Time of day in 1 second intervals (treated 
as an unsigned number). Only required if 
INSWT, bit 15 is ON. 


DATE Four-word array of ASCII characters in the following format: 


mm-dd-yy 


TIME ASCIl array of either three (INSWT bit 14 off) or five (INSWT bit 
15 on) words in format: 


bhh:mm:ssb 


The last two words are omitted if INSWT bit 14 is off 


(b = blank). 


See also, FMIDAT, GETDAT. 
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FNDVAL(VALUE, SIZE, ARRAY) 

Searches an array for the integer value specified. 
VALUE _ Value to search for. 
SIZE Number of elements in array (=0). 
ARRAY _ Array of integers to be searched. 

=Q VALUE not in array. 


>0 Array index for location of integer equal to VALUE. 
<Q _ Illegal, should not be returned. 
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FREAD(CHANNEL, DLOC, COUNT,BUF,OPTIONS) 


Reads an open file or catalog. 


CHANNEL 
DLOC 
COUNT 
BUF 
OPTIONS(1) 
Bit 
0 
1 ON 
OFF 
2 ON 
3-14 
15 ON 
OFF 
OPTIONS(2) 
OPTIONS(3) 


Channel number assigned to the file. 
Two word relative disc location into file. 
Number of machine words to read (single word). 


Array of words to read. 


(Leftmost bit is 0.) 
Reserved (must be zero). 
Do not wait until read is done, return immediately. 


Request an I/O flag, address will be returned in 
OPTIONS(2). 


Wait until read is done before returning (normal). 
Return actual count of words read in OPTIONS(3) 
Reserved (must be zero). 


Error condition results in error FLAG returned as function 
name. 


Error condition results in the call ERROR(FLAG). 


1/O flag address if OPTIONS(1) Bit 1 is on Must call 
TESTIO to test and release the |/O flag. 


Actual count of words read if OPTIONS(1) bit 2 is ON. 


OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 
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For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


e The file or catalog must be open for read, modify, or create. 


If the file is not contiguous, the requested disc read may result in several 


physical disc reads. If so, the function return will not be immediate. 
Instead, the value will be returned after the last physical disc read is in- 


itiated. 


The size of OPTIONS is determined by the bit pattern of OPTIONS(1). If 


no values are to be returned in OPTIONS(2-3) the argument OPTIONS 
need only be one word long. 


FREEPG(SPID) 


Frees memory pages. 


RESTRICTIONS: 


Memory pages can only be freed under the following conditions. 


e Only the owner can free pages. 


e They must not be in address space. 


e No other users may be using them. 


¢ No I/O may be affecting the pages. 


SPID 


0 
E020 
F024 
E070 


System Page ID of the page to be deallocated. 


No errors. 

Illegal system page identifier (SPID). 

Calling task does not own the page specified by SPID. 

The page specified by SPID is not in the callers page frame. 
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FWRITE(CHANNEL,DLOC,COUNT,BUF,OPTIONS) 


Writes to a file that is open for modify or create. 


CHANNEL 
DLOC 
COUNT(1) 
COUNT(2) 
BUF 
OPTIONS(1) 
Bit 
0 ON 
OFF 
1 ON 
OFF 
2 ON 
3 ON 
OFF 
Note 


Channel number assigned to the file. 
Two word relative disc location into file. 
Number of machine words to write (single word). 


Minimum number of sectors to be allocated on an 
expanded write. 


Array of words to write. 


(Leftmost Bit is 0.) 


Upon EOF condition, allocate any additional space as 
needed. Additional space may not be contiguous. Con- 
tinue writing to the disc. 


Any attempt to write past EOF generates an error condi- 
tion. 


Do not wait until write is done — return immediately. 
Request an I/O flag, with address to be returned in 
OPTIONS(2). 


Wait until write is done before returning (normal). 
Return actual count of words written in OPTIONS(3). 


On EOF condition, allocate at least the number of sectors 
specified in COUNT(2). 


On EOF condition, allocate exactly the additional space 
necessary to complete the write request. 


Bit 1 must be ON for bit 3 to be valid. 
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4-14 ~ Reserved (must be zero). 


15 ON Error condition results in error FLAG returned as function 
name. 


OFF _ Error condition results in the call ERROR(FLAG) 
—OPTIONS(1) bit 1 ON: 


OPTIONS(2) I/O flag address TESTIO must be called to test and 
release the I/O flag. 


OPTIONS(3) Returns the count of words written. 
OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM 


If the file is not contiguous, the requested disc write may result in several 
physical disc writes. The function value will not be returned until after the 
last physical disc write is initiated. 
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GETBIT(STRING, INDEX) 

Returns the value of a given bit. 

STRING Bit string array. 

INDEX Bit position in STRING (Leftmost bit is 0). 


0 Bit is OFF. 
1 Bit is ON. 


GETDAT(ARRAY) 
Gives the current date and time in system date and time format. 


ARRA — Two-word date and time array: 


Word 1 Bit (Leftmost bit is 0.) 
0 AM/PM indicator: ON for PM, OFF for 
AM. 


1-6 Number of years since 1960 (0 to 63). 
7-10 Month (1-12). 
11-15 Day (1-31). 


Word 2 Time of day in 1 second intervals (interpreted as an 
unsigned integer) 


See also, FMIDAT, FMTDAT. 
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The GETFILE utility package is used to access text files on a line-by-line 
basis. The normal sequence for reading from a text file would be to open 
with GETFILE, read lines of text with GETLINE or GETLINEB, and close 
with GETCLOSE. There are also four routines for manipulating the sequen- 
tial access pointer: GETCLEAR, GETMARK, GETPOS, and GETSTART. 


GETFILE(FSB, BUF, BUFSIZ, FNAME,OPTIONS) 


Opens a text file for input on a line-by-line basis. 


FSB 
BUF 
BUFSIZ 
FNAME 
OPTIONS(1) 
Bit 
0 ON 
1 ON 
2-13 
14 ON 
15 ON 


OFF 


File Status Block (eight words, see below) FSB(1) MUST 
be set to 1. 


Output Buffer. 
engun of buffer in sectors. 


Filename (without the &BCD) in the form returned by 
FMNAME: 


Word 1 Character count (includes ‘!’). 
Word 2-n Filename (includes ‘!’). 


(Leftmost bit is 0.) 
Return extended array in OPTIONS (2-16). 


FNAME (42-44) contains the fast lookup information 
returned from CATWALK. 


Reserved (must be xero). 
Return normal array in OPTIONS (2-5). 


Error condition results in error FLAG returned as a func- 
tion name. 


Error condition results in the call ERROR(FLAG). 
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OPTIONS(1) bit 14 ON: 


(Word) Normal Array. 
(2-3) Disc location, always (0,0). 
(4-5) Total sector count of file. 


OPTIONS(1) bit 0 ON: 


(Word) Extended Array. 
(2-3) Disc location, always (0,0). 
(4-5) Total sector count of file. 
(6) Creation date. 
(7) Time of day of creation in one-second inter- 
vals. 
(8) Access date. 
(9) File protection group. 
Bit (Leftmost bit is 0.) 
0-7 Reserved. 
8-15 File protection group. 
(10) File status, with bit ON: 
Bit (Leftmost bit is 0.) 
0 In use. 


Opened for modify in place. 


2 To be deleted when closed if use count is 0 
(i.e., old file of create with supersede). 


Opened for create. 
Temporary entry for create with supersede. 


Opened for regular read. 


Oo oo fh W 


Reserved. 
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7 File is a catalog. 
8 File is a volume. 
9-15 Reserved. 
(11) Number of users currently accessing file or 


included file — incremented each time the 
file or included file is opened, decremented 
each time it is closed. 


(12) Contiguous data flag: | 
0 All data allocated contiguously. 
N Data not contiguous, N is sector 


count (N 0) of first contiguous chunk 
of the file (if file has 0 length this is 
indicated by ARRAY(3-4)). 


(13) User-defined attribute value. 
(14) User-defined attribute value. 
(15) CHKSUM. 


(16) File type 

Bit (Leftmost bit is 0.) 

0-7 = ~ Not task protected. 

>0 1 + number of task which has protected the 
file. 

8-15 Not defined. 
Catalog. 
Object. 
Text. 
Configuration. 
Reserved. 
PEP object code. 
Core image (overlay). 
Command table 
Loader data file (symbol table or library). 
Reserved. 
Accounting table. 
Reserved. 
280 binary files. 
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Reserved for CGOS. 

CADDS 4 part files. 

CADDS 4 TVF files. 

CADDS 4 figure files. 

Reserved for CADDS 4. 

Unused. 

Reserved for batch files. 

Unused. 

Work files (detected on FMCLEAR). 


Description of FSB (File Status Block) 


FSB(1) Status: 1. No file open. 
2. Reading file. 
3. At end-of-file. 
4. Reading without BUF in memory. 
5. At EOF without BUF in memory. 
FSB(2) Input channel number. 


FSB(3-4) Relative DLOC in file. 
FSB(5-6) Bytes remaining in file. 


FSB(7) Byte pointer. 


FSB(8) Size of user’s disc buffer in words. 


OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


Refer to ERROR. For description of FILE MANAGER ERRORS. 


® Routines in the GETFILE family have no local variables to maintain. Only 
the integrity of FSB and BUF is important. 


e BUFSIZ must be a multiple of SECTSIZ that is less than 32K bytes 


(16384 words). 
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GETLINE(FSB, BUF,MAX,LEN, LINE) 

Retrieves next line from text file opened by GETFILE. 
FSB File Status Block. 

BU Disc buffer. 

MAX Length of line buffer in characters. 

LEN Length of the line (-1 if at END OF FILE). 
LINE Character string array of LEN characters. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


MAX must be greater than or equal to the longest line in the file, otherwise 
an error will be triggered. 
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GETLINEB(FSB,BUF,MAX,LEN,LINE,OFFSET) 


Retrieves next line from text file opened by GETFILE. This routine is 
equivalent to GETLINE with the addition of a byte offset. 


FSB File Status Block. 
BUF Disc buffer. 
MAX Length of line buffer in characters. 


OFFSET Byte offset in LINE (counted from 0) for the contents of BUF. 
LEN Length of the line (-1 if at END OF FILE). 
LINE Character string array of LEN characters. 


e Complete documentation, including a full description of the FSB (File 
Status Block), may be found under GETFILE. 


e This routine must be used in conjunction with LIB.FM.GETFILE. 


e MAX must be greater than or equal to the longest line in the file, other- 
wise an error will be triggered. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 
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GETCLEAR(FSB) 

Marks the FSB (File Status Block) of an open file to indicate that the text 
file buffer is no longer available and must be loaded into memory the next 
time that the routine GETLINE is called. 

FSB File Status Block. 


e Additional documentation, including a description of the FSB (File 
Status Block), may be found under LIB.FM.GETFILE. 


e This routine must be used in conjunction with LIB.FM.GETFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM 


GETPOS(FSB,POS) 

Used with textfiles, restores a position marked by GETMARK. 
FSB File Status Block. 

POS(7) Saved position from GETMARK. 


¢ Complete documentation, including a full description of the FSB (File 
Status Block), may be found under GETFILE. 


e This routine must be used in conjunction with LIB.FM.GETFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM 
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GETMARK(FSB,POS) 

Marks the current position in a text file being read by GETFILE. 
FSB File Status Block. 

POS(7) Saved position information. 


¢ Complete documentation, including a full description of the FSB (File 
Status Block), may be found under GETFILE. 


e This routine must be used in conjunction with LIB.FM.GETFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


GETSTART(FSB,BUF) 

Moves the pointer to the top of a text file opened by GETFILE. 
FSB File Status Block. 

BUF Disc buffer. 


e Complete documentation, including a full description of the FSB (File 
Status Block), may be found under GETFILE. 


e This routine must be used in conjunction with LIB.FM.GETFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 
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GETCLOSE 
SYNTAX GETCLOSE(FSB,BUF) 
PURPOSE Closes the text file opened by the routine GETFILE. 
INPUT FSB File Status Block. 
BUF Disc buffer. 
NOTES | e Additional documentation, including a description of the FSB (File 
Status Block), may be found under LIB.FM.GETFILE. 
e This routine must be used in conjunction with LIB.FM.GETFILE. 
ERRORS For a description of FILE MANAGER ERRORS, refer to: 


SYSNEWS.ERROR.FM. 
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GETFLD(STRING, FBIT, SIZE) 

Retrieves the value in a field and returns it as a right-justified integer. 

STRING Bit string containing the field to be returned. 

FBIT The location of the field, specified by the displacement in 
bits between the high-order (leftmost) bit of the field and the 
high-order bit of string. 


SIZE The size of the field in bits (0 < SIZE < 17). 


An integer value for the contents of the field. 
More exactly: 


FOR | = 1,SIZE. 
RETURN (15-SIZE+1) STRING(FBIT—1+1). 


RETURN and STRING are treated as bit strings indexed from 0. 
If there is an error in the argument, GETFLD calls ERROR. 


LIB.DBLSH must also be loaded. See also TSTBIT, SETBIT, CLRBIT, 
PUTBIT, PUTFLD, and GETBIT. 
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GETLABEL(TBLABEL,SAVLABEL) 


Accesses a system label from the TASKBLOCK and saves it in: 
SAVLABEL. 


TBLABEL Identifies the desired system label from the TASKBLOCK: 


—1  TAPERLBL 
—2 SYSERLBL 
—3 INTRQUIT 
SAVLABEL Destination of the label (2-word array). 


e For safety, GETLABEL should only be used in user address space. 


e System label values and references are the same as LBLSET and 
LBLGO. 


‘FOOD’x — TBLABEL specified is illegal (bad arg). 
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GETPG(BUFFER,SPID,PERMIT) 

Reads a page slot of a user’s page frame, returning the: 
e SPID of the system memory page in the page slot. 

e Permission associated with the slot. 


BUFFER Amemory buffer, one memory page long (‘800’X words) that 
is aligned on a page boundary. 


SPID System Page ID of the page in the page slot specified by 
SLOTID. If there is no page in the slot, SPID will be NULL. 


PERMIT User access for the page slot identified by SLOTID: 
P&RW Any access is legal. 
P&RO Read-only. 
P&NO No legal access. 


0 No errors. 
E010 BUFFER is not aligned on page boundary. 


The symbolic constants are defined in SYM.EQU.MEMMAN and 
SYM.EQUF.MEMMAN. 
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GETPGP(SPID,PROT) 

Reads the parameters of a system page. 

SPID System page ID of a memory page. 

PROT Protection attributes of this page: 
P&RW Any access is legal. 
P&RO Read access only. 
P&NO No legal access. 


0 No errors. 
EO20 _ Illegal system page identifier (SPID). 


The symbolic constants are defined in SYN.,EQU.MEMMAN and 
SYM.EQUF.MEMMAN. 
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GETPPTD(ARG) 
Attaches punch paper tape unit (PPTDEV) to a task. 
ARG Set as follows: 

If PPTDEV is already attached, ARG = 0. 


If no PPTDEV is attached, prompts for a task unit name, unique 
name, or unit type to be typed in at the COMDEV: 


e No name typed in, ARG = -—1. 
e Name typed in: 
Two-character name, attempts to declare unit as PPTDEV. 


Four-character name, attempts to attach a unit with this unique 
name, or of this type as ‘PP’, and attach it as PPTDEV 


If attaching or declaration is unsuccessful, asks for another name. Other- 
wise ARG = 0. 


ARG 
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GETPUNCH 

SYNTAX GETPUNCH(VALUE) ~ 

PURPOSE Gets the parity option for the PPTDEV. 

OUTPUT VALUE parity option for task PPTDEV, where: 
0: no parity, transparent data transfer. 
1: odd parity. 
2: even parity. 
3: marked parity, MSB of byte set to 1. 
4: spaced parity, MSB of byte set to 0. 

FUNCTION 0 No error detected. 

RETURN — No PPTDEV for task. 


OTHER Error return from GETDEV routine. 
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GETRPTD 
SYNTAX GETRPTD(ARG) 
PURPOSE Attaches read paper tape unit (RPTDEV) to a task. 
OUTPUT ARG Set as follows: 
If RPTDEV is already attached, ARG = 0. 


If no RPTDEV is attached, prompts for a task unit name, unique 
name, or unit type to be typed in at the COMDEV: 


e No name typed in, ARG = -1. 
e Name typed in: 


Two-character name, attempts to declare unit as 
RPTDEV. 


Four-character name, attempts to attach a unit with this 
unique name, or of this type as ‘RP’, and attach it as 
RPTDEV. 


If attaching or declaration is unsuccessful, asks for another name. Other- 
wise ARG = 0. 


FUNCTION ARG 
RETURN 
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GETSTAT 

SYNTAX GETSTAT(TYP, TYPID, TIMBLK) 

PURPOSE Reads task or system statistics blocks. 

INPUT TYP Type of statistics block to return: 
=1, System statistics block (SYSSTAT, 4 Words). 
=2, Task statistics block (TASKSTAT, 4 words). 
=3, Total CPU time used by logged out tasks (2 words). 

TYPID Contains address of taskblock when TYPE =<2. 

Type TSKADDR 
= =0 Return task CPU usage. 
= #0 TSKADDBR _taskblock pointer. 
#2 Ignored 


OUTPUT TIMBLK Double-word array to receive either task or system statistics | 
block. 
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GETTASK 

SYNTAX GETTASK 

PURPOSE Returns task number. 

FUNCTION Task number (=0). 

RETURN 

NOTE GETTASK may only be called from TPL routines. For FORTRAN version, 
see GETTASKF. 

GETTASKF 

SYNTAX GETTASKF(INUM) 

PURPOSE Returns task number (FORTRAN version). 

OUTPUT INUM The task number. 

FUNCTION The task number. 

RETURN 
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GLP(DEVICE, ANTECC,CNT,LINE, POSTCC) 


Outputs a line of characters to device(s). 


DEVICE 
0 
‘CM’ 
a + v 
‘HD’ 
‘LP’ 


ANTECC 


CNT 
LINE 


POSTCC 


Device Selector: 


Use devices and/or hardfile selected by the toggles. 
COMDEV only (need not be toggled on). 

Use the COMDEV plus any other devices and/or hardfile 
selected by the toggles. 

HARDEV/hardfile only (must be toggled on). 

Use physical HARDEV with implicit page eject. The task must 
have a device declared as the task HARDEV. 


Carriage control before the line is printed: 

‘11'x Do page eject before the line. 

0 Print on the current line. 

Other |Number of lines to skip before printing. 
Number of characters in the line. 
Characters to output (will be followed by a carriage return). 
Carriage control after the line is printed: 

TY Do page eject after the line. 


0 No carriage advance (allows overprinting). 
Other Number of lines to skip after printing. 
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HEAPSORT 
SYNTAX HEAPSORT(ARRAY,N,COMPFUN) 
PURPOSE Sorts an internal file of single word records. A user-supplied function 
compares keys. 
INPUT ARRAY Internal file of single word records. 
N Number of records in the file. 
COMPFUN Record comparison function with a return that depends 
on the relation of KEY1 and KEY2: 
KEY COMPFUN 
< KEY2 <0 
= KEY2 = 0 
> KEY2 > 0 
OUTPUT ARRAY Sorted internal file. 
NOTE The time required for HEAPSORT is O(N log N). 
HEXBCD 
SYNTAX HEXBCD(HEX, BCD) 
PURPOSE Converts a hex word to BCD. 
INPUT HEX Hex word to be converted. 
OUTPUT BCD Two-word array containing four characters. 
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HEXDMP 

SYNTAX HEXDMP(LOC1,LOC2, BIAS, BUF) 

PURPOSE Creates hex BCD dump of an array. 

INPUT LOCT Lower hex bound subscript to appear on dump. 

LOC2 Upper hex bound subscript to appear on dump. 

BIAS Hex subscript corresponding to first word of BUF (same units 
as LOC1 and LOC2). BIAS can be used to dump portions of 
core before BUF without knowing their address. 

BUF Array containing information to be dumped. 

NOTE Each line (between LOC1 and LOC2) contains start address for the line, 
and eight hex dump words. Core constants appear as ...._. Lines identical 
to the previous line will not be printed. Omitted lines have .... in the 
address field. One line skipped at the end of HEXDMP output. 

EXAMPLE To dump ’100’x words starting at array Q, use: 


CALL HEXDMP(0,’FF’x,0,Q) 
To dump ‘10’x words just before array Q, use: 


CALL HEXDMP(0,’10’x,’10’x,Q) 
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HEXLST(LIST) 


Scans the input stream for a hex bounds list. 


LIST(1) Count of pairs in list (all hex integers) 
LIST (2) XXXX4q 
LIST(3) YYYY4 (or XXXX1, if YYYY] omitted) 
LIST(n*2) XXXXp 


LIST(n*2+ 1) YYYYn (or XXXXn, if YYYY, omitted) 

e The text being scanned has the form: 

XXXX1 (—YYYY4 ) ,...,XXXXm (— YYYVYp— ) 

e INITCHAR and NXTCHAR set up BCD string and system overlay globals 
for HEXLST. The two routines are automatically called to set up scan- 
ning of the command line. They must be explicitly called to initialize 
scanning of any other stream characters (i.e., a line input with TYPIN). 


@ HEXLST will push past blank characters upon termination. 


e See INTLST and HEXNUM. 


5-85 


The information and drawings contained herein-are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 


and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


HEXNUM 

SYNTAX HEXNUM(HEXVAL) 

PURPOSE Scans a hex number from the input stream. 
OUTPUT HEXVAL Hex integer result. 

NOTES e The hex number must fit in a 16 bit integer. 

e INITCHAR and NXTCHAR set up BCD string and system overlay globals 
for HEXNUM. The two routines are automatically called to set up scan- 
ning of the command line. They must be explicitly called to initialize 
scanning of any other stream of characters (i.e., a line input with 
TYPIN). 

© HEXNUM will push past blank characters upon termination. 

HIBERNS 

SYNTAX — HIBERN8(TIMER) 

PURPOSE Deactivates a task for a specified time period. 

INPUT TIMER Number of clock ticks (10 ms/tick) task is to be deactivated. 
NOTE The task is reactivated when the timer reaches zero. If the routine is called 


with an argument of zero or less, then the task will be deactivated for 
(32768 + TIMER) + 32767 clock ticks. 
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IDENT(NAME) 


Scans the input stream for an eight-BCD-character identifier beginning 
with an alphabetic character. 


NAME ~— Ejight-BCD-character identifier,left-justified, and padded with 
blanks. 


‘801'x First character is not an & or an aiphabetic character. 

‘802'x More than eight characters in identifier. 

e INITCHAR and NXTCHAR set up BCD string and system overlay globals 
for IDENT. The two routines are automatically called to set up scanning 
of the command line. They must be explicitly called to initialize scanning 
of any other stream of characters (i.e., a liné input with TYPIN). 


e IDENT will push past blank characters upon termination. 


e The scan terminates when a special character is found. 


IFIXD(D) 
Converts a double precision real to a single-word integer. 
D Double precision real number. 


Single-word integer. 
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INITCHAR(ARRAY,N) 

Initializes array and character count for NXTCHAR. 
ARRAY Array of characters. 

N Count of characters in array. 


e INITCHAR and NXTCHAR must be called in preparation for all scan 
routines. 


INITCHAR and NXTCHAR are automatically called to set up scanning of 
the command line. The two routines must be explicitly called to initialize 
scanning of any other stream of characters (i.e., a line input with 
TYPIN). 


Initializes character accessing function NXTCHAR for use on ARRAY 
with N characters. NXTCHAR sets up system overlay globals. 


INITNM(NMLST,NINFO) 


Initializes scanning of the input stream for list of comma-separated names. 
The characteristics of a name are defined by FMIDNT. 


NMLST: FM NAME LIST of the form: 


Word 1: Count of names. 
Word 2-n: M-+ Bytes for each name as follows: 
BYTE 0: Count of characters in name. 


BYTES 1-M: Characters in name. 
NINFO: = Two-word array for scanning name list. 
INITNM is part of a package that includes FMNLST and NXTNAM. Call 


FMNLST to get the list of names, and then call INITNM and NXTNAM to 
get individual names from the list. 
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INSESORT(ARRAY,N, COMPFUN) 


Sorts an internal file of single word records. Keys are compared by a user- 
supplied function. 


ARRAY Internal file of single word records. 
N Number of records in the file. 


COMPFUN Record comparison function with a return that depends 
on the relation of KEY1 and KEY2: 


KEY? COMPFUN 
< KEY2 <0 
= KEY2 = (0 
> KEY2 > 0 


ARRAY Sorted internal file. 


INSESORT uses a straight insertion sort. The time required is O(N ). This is 
a stable sort. 
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INSESRTN(RECS,NREC, COMPFUN,RECLEN,REC) 
Sorts records using a straight insertion sort. 

RECS Array containing data to be sorted. 
NREC Number of records to be sorted. 


COMPFUN Record comparison function with a return that depends 
on the relation of KEY1 to KEY2: 


KEY1 COMPFUN 
< KEY2 < 0 
= KEY2 = 0 
> KEY2 > 0 


RECLEN Length of record, in words. 

REC A caller supplied scratch, RECLEN words long. 

Sorted array. 

e INSESRTN is a straight insertion sort that follows the Knuth Algorithm 


(Knuth, Vol. 3, p. 87). Comments of the form, SN, refer to steps in the 
Knuth Algorithm. 


SHELSRTN, a shell sort, is generally preferable to INSESRTN unless a 
stable sort is required. It is significantly faster than INSESRTN when 
more than 25 records are sorted. The two routines have similar amounts 
of code. 
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INT(RESULT) 
Scans a decimal integer from the input stream. 
RESULT Positive or negative decimal integer. 


e INITCHAR and NXTCHAR set up character string and system globals 
for INT. 


e The two routines are automatically called to set up scanning of the 
command line. They must be explicitly called to initialize scanning of any 
other stream of characters (i.e. a line input with TYPIN). 


e INT will push past blank characters upon termination. 


INTBCD(NUM,CHARS) 

Converts an ineaet to a character string. 

NUM Integer to be converted. 

CHARS __ Three-word array containing character string. 
e Character string is right-justified in CHARS. 

e Unfilled characters are padded with blanks. 


e A minus sign, if needed, is inserted in front of the leftmost character. 
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INTLST(LIST) 


Scans the input stream for a decimal bounds list. 


LIST(1) Count of pairs in list (all hex integers). 
LIST(2) X4 


LIST(3) Y1 (or X4, if Y1 omitted)... 


LIST(n*2) Xp se 
LIST(n*2+1) Y, (or Xp, if Y,, omitted). 


e The text string being scanned has the form: 
X4(—¥4) ,.-:Xp_l — Yay) 


e INITCHAR and NXTCHAR set up character string and system globals 
for INTLST. 


e The two routines are automatically called to set up scanning of the 
command line. They must be explicitly called to initialize scanning of 
any other stream of characters (i.e., a line input with TYPIN). 


e INTLST will push past blank characters upon termination. 
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IPDL(P,L) 

Initialize a push down list. 

P Array to be a push-down list. 

L Length of the P array. 

P Push-down list. 

Using IPDL allows the following routines to use the push-down list: 
POP 
POPN 


PUSH 
PUSHN 


ISNGL(L) 
Converts a double integer to an integer. 
L Double integer. 


Integer. 
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LABS(I) 
Computes the absolute value of a double integer. 
Double integer. 


Absolute value of |. 


LBLGO(ARG) 
Transfers control to label set in LBLSET. 


ARG-1  TAPERLBL to be used. 

ARG-2 SYSERLBL to be used. 

ARG-3 INTRQUIT to be used. 

Other Two-word label array containing information set in LBLSET. | 


‘FOOD’x = ARG(1) bad (is core constant or <0). 
¢ On a LBLGO, the roll table pointer is set to the value in ARG(2), and 
ARG(1) is put into return address location of that roll table entry, a 


RETURN is then executed. 


See also, GETLABEL, PUTLABEL, LBLSET, and RESETLBL. . 
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LBLSET(ARG,LBL) 


Sets up information for LBLGO transfer. 


LBL Statement label in calling code to which control is to be transfer- 


red if LBLGO.(ARG) Is called. 


ARG-1 TAPERLBL to be set. 
ARG-2 SYSERLBL to be set. 
ARG-3  INTRQUIT to be set. 
Other ARG is two-word label array to be set. 


The selected two-word label array is set as: 


(1) Address of LBL. 
(2) Current roll table pointer. 


LBLSET can only be called from TPL because FORTRAN statement 
labels may not be passed as arguments. 


The following calls will reset the system labels to default operation: 
CALL RESETLBL( - 1) 
CALL RESETLBL( — 2) 
CALL RESETLBL( — 3) 


All system labels are set to the default values at the start of every 
command. 


5-95 


LDBYTF 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


LDBYTF 
SYNTAX LDBYTF(ARRAY,N) 
PURPOSE Loads a byte (FORTRAN version). 
INPUT ARRAY _ Array containing bytes. 

N Byte position (N= 1). 
FUNCTION The Nth byte of ARRAY in byte format. 
RETURN 
COMMENT Byte indices start at 1. 
LDBYTT 
SYNTAX LDBYTT(ARRAY,N) 
PURPOSE Loads a byte. 
INPUT ARRAY _ Byte array. 

N Byte position (N= 0) 
FUNCTION The Nth byte of ARRAY in byte format. 
RETURN 
COMMENT Byte indices start at 0. 
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LDCHRF(ARRAY,N) 
Loads a character (FORTRAN version). 


ARRAY _ Array containing bytes. 
N Byte position (N= 1). 


The Nth byte of ARRAY in character format. 


Byte indices start at 1. 


LDCHRT(ARRAY,N) 
Loads a character (TPL version). 


ARRAY _ Array containing bytes. 
N Byte position (N= 0). 
The Nth byte of ARRAY in character format. 


Byte indices start at 0. 


5-97 


LFIX — 


LFIX 
SYNTAX 
PURPOSE 
INPUT 


FUNCTION 
RETURN 


LFIXD 
SYNTAX 
PURPOSE 
INPUT 


FUNCTION 
RETURN 


5-98 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


LFIX(F) 
Converts a real number to a double integer. 
F Real. 


Double integer. 


LFIXD(D) 
Converts a double precision real to a double integer. 
D Double precision real. 


Double integer. 
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LP(CARRCONT,ARGCNT,LINE) 


Outputs a line of characters to COMDEV (and HARDEV if hard copy toggle 
on). 


CARRCONT Carriage control. 


='0-F’x Skip CARRCONT lines before outputting characters. 
='11'x Eject page before outputting characters 


ARGCNT Number of characters to be output. 
LINE Packed character string. 
e The system routine CHKINTR is called when a line of characters is out- 


put by LP. This may result in characters being removed from the TIS 
(see CHKINTR). 


See also TYPE, TYPOUT. 
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MAXIMUM 
SYNTAX MAXIMUMiI,J) 
PURPOSE Finds the larger of two unsignea integers. 
INPUT | Unsigned Integer. 
J Unsigned Integer. 
FUNCTION Larger of | and J.. 
RETURN 
MIRIMUM 
SYNTAX MINIMUMI(I,J) - 
PURPOSE Finds the smaller of two unsigned integers. 
INPUT | Unsigned integer. 
J Unsigned integer. 
FUNCTION Smaller of | and J. 
RETURN 
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MODIFILE(FSB,BUF,BUFSIZ, FNAME,OPTIONS) 
Opens a binary sequential file for modification. 
FSB File Status Block. 

BUF Disc buffer. 

BUFFSIZ Size of disc buffer in sectors. 
FNAME Filename in FM format: 


Word 1 Character count (including !). 
Word 2-n_ _— Filename (terminated by !). 


OPTIONS(1) 
Bit (Leftmost bit is 0.) 
0 ON Return extended array in OPTIONS(2-16). 
14 ON Return normal array in OPTIONS(2-5). 


15 ON Function returns errors. 


OFF _ Errors are processed by the system error handler. 
OPTIONS(2-16) _ File information array: 


OPTIONS(1) bit 0 OFF: 


(Word) Normal Array 
(2-3) Disc location always (0,0). 
(4-5) Total sector count of file. 


OPTIONS(1) bit 0 ON: 


(Word) Extended Array 
(2-3) Disc location always (0,0). 
(4-5) Total sector count of file. 
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(6) 
(7) 
(8) 
(9) 
Bit 
0-7 
8-15 
(10) 
Bit 
0 
2 
3 
4 
5 
6 
7 
8 
9-15 
(11) 


Creation date. 
Creation time, in ciie-second intervals. 
Access date. 


File protection group: 


Reserved. 


File protection group 
File status: 


Status as indicated when bit ON. 


File in use. 
File opened for modify in place. 


File to be deleted when closed if use count is 
0 (i.e., old file of create with supersede). 


File Open for create. 


This entry is a temporary one for create with 
supersede. 


File opened for regular read. 
Reserved. 

File is a catalog. 

File is a volume. 


Reserved. 
Use count: 


Record of number of users currently access- 
ing file or included file, incremented each 
time the file or included file is opened, 
decremented each time the file or included 
file is closed. 


OUTPUT 
(Continued) 
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(12) Contiguous data flag 
0 Contiguous data allocation. 


>0 Data not contiguous, N is sector count of 
the file’s first contiguous chunk of data (if 
file has O length this is indicated by 


ARRAY (3-4)). 
(13) User defined attribute value. 
(14) User defined attribute value. 
(15) CHKSUM. 
(16) File type 
Bit (Leftmost bit is 0.) 
0-7 = Not task protected. 
>0O 1 + number of task which has protected 
the file. 
8-15 0 Not defined. 
1 Catalog. 
2 Object. 
3. Text. 
4 Configuration. 
5 Reserved. 
6 PEP object code. 
7 Core image (overlay). 
8 Command table. 
9 Loader data file (symbol table or library). 
A Reserved. 
B Accounting table. 
C-E Reserved. 
F 280 binary files. 


10-1F Reserved for CGOS. 
20 CADDS 4 part files. 
21 CADDS 4 TVF files. 
22 CADDS 4 figure files. 
23-2F Reserved for CADDS 4. 
30-AF Unused. 
BO-BF Reserved for batch files. 
CO-FE. Unused. 
FF Work files (deleted on FMCLEAR). 
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FUNCTION OPTIONS(1) bit 15 ON: 
RETURN 
0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


ERRORS For description of FILE MANAGER ERRORS, refer to SYSNEWS 
ERROR.FM. 
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MOPEN(CHANNEL, FILENAME, OPTIONS, ARRAY) 


Opens a file for modify in place. 


FILENAME 


(Word) 


Restriction 


Read and write access are needed. File must 
not be in use. 


(1-41) Full ASCII filename with a period (.) as delimiter between com- 
ponents and an exclamation mark (!) following the last 
character. Each component of the filename must be 20 
characters or less. 


OPTIONS(1) 
Bit 
0 ON 
OFF 
1-12 
13. ON 
OFF 
14 ON 
15 ON 
OFF 


(Leftmost bit is 0.) 


Return extended array. 


Return normal array. — 
Reserved (must be zero). 


OPTIONS(2) contains additional option data. 
OPTIONS(2) ignored. 


Return working directory name count in OPTIONS(3) 
followed by characters named in OPTIONS (4-42). If 
working directory not enabled, value is returned in 
OPTIONS(3). 


Error condition results in error FLAG returned as function 
name. 


Error condition results in the call ERROR(FLAG). 
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OPTIONS(2) 
Bit (Leftmost bit is 0.) 
0-15 Reserved (must be zero). 


OPTIONS(1) bit 14 ON: 


OPTIONS(3) Directory name character count, or < 0 if working 
directory not enabled. 


OPTIONS(4-42) Directory name for OPTIONS(3) number of 
characters. 


ARRAY File information array: 


OPTIONS(1) bit 0 OFF: 


(Word) Normal Array 
(1-2) Disc location always (0,0). 
(3-4) Total sector count of file. 


OPTIONS(1) bit 0 ON: 


(Word) Extended Array 
(1-2) Disc location always (0,0). 
(3-4) Total sector count of file. 
(5) | Creation date. 
(6) Creation time, in one-second intervals. 
(7) Access date. 
(8) File protection group: 
Bit 
0-7 Reserved. 
8-15 File protection group. 


OUTPUT 


MOPEN 
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(9) File status: 
Status as indicated when bit ON. 
Bit 


0 File in use. 

1 | File opened for modify in place. 

2 File to be deleted when closed if use count is 
0 (i.e., old file of create with supercede). 
File Open for create. 

4 This entry is a temporary one for create with 

supersede. 

File opened for regular read. 

Reserved. 

File is a catalog. 

File is a volume. 

-15 Reserved. 


“IO O1 


© 0 


(10) Use count: 


Record of number of users currently access- 
ing file or included file, incremented each 
time the file or included file is opened, 
decremented each time the file or included 
file is closed. 


(11) Contiguous data flag. 
0 Contiguous data allocation. 
>0 Data not contiguous, N ts sector count of 
the first contiguous chunk of the file (if file 
has Q length this is indicated by 
ARRAY (3-4)). 


(12) User defined attribute value. 
(13) User defined attribute value. 
(14) CHKSUM. 
(15) File type 

Bit Leftmost bit is 0. 

0-7 =0Q Not task protected. 


>0 1 + number of task which has protected 
the file. 
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8-15 


WPMOANDUAWNH=O 


% 
m 


—_ 
; 

cones 

1ST 


Not defined. 
Catalog. 

Object. 

Text. 

Configuration. 
Reserved. 

PEP object code. 
Core image (overlay). 
Command table. 
Loader data file (symbol table or library). 
Reserved. 7 
Accounting table. 

Reserved. 

280 binary files. 

Reserved for CGOS. 

CADDS 4 part files. 

CADDS 4 TVF files. 

CADDS 4 figure files. 

Reserved for CADDS 4. 

Unused. 

Reserved for batch files. 

Unused. 

Work files (deleted on FMCLEAR). 


CHANNEL Channel number assigned to the file. 


OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


For description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 
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MOV(CNT,ARR1,ARR2) 

Moves integer data from one array to another. 
CNT Number of integer words to be moved. 
ARR1 Array containing integer data. 


ARR2 Array filled with data from ARR1. 


MOVB(CNT,ARR1,ARR2) 


Moves integer data from one array to another, starting at the end of the 
array and proceeding backwards through the array. 


CNT Number of integer words to be moved. 
ARR1 Last word of source array. 


ARR2 Last word of destination array, filled with data from the source 
array. 
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MOVD(CNT,ARR1,ARR2) 

Moves double precision real data from one array to another. 

CNT Number of double real precision numbers to be moved. 
ARR1 Source array. 


ARR2 Destination array, filled with data from the source array. 


MOVEWORD(ARRAY1,0FF1,CNT1,ARRAY2,OFF2,CNT2,NUM2, 
EFLAG) 


Moves a word (alphabetic string) from one array to another, stopping 
before any non-alphabetic character. Lower case characters are converted 
to upper case. 

ARRAY 1 Packed array of characters to be moved. 

OFF1 Byte offset within ARRAY‘1 to start. 

CNT1 Total number of characters in ARRAY1. 


ARRAY2 Destination array. 


OFF2 Byte offset within ARRAY’1 to start. 
CNT2 Size in bytes of ARRAY2. 

NUM2 Second double integer to be tested. 
EFLAG Error flag: 


Q No errors. 
#0 Move would overflow destination buffer. 
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MOVF(CNT,ARR1,ARR2) 

Moves real data from one array to another. 

CNT Number of real numbers to be moved. 
ARR1 Source array. 


ARR2 Destination array, filled with data from the source array. 


MOVL(CNT,ARR1,ARR2) 

Moves double precision integer data from one array to another. 

CNT Number of double integer precision numbers to be moved. 
ARR1 Source array. 


ARR2 Destination array, filled with data from the source array. 
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MVBYTFICNT,ARRAY1,N1,ARRAY2,N2) 


Moves bytes (or characters) from one array to another. 


CNT 
ARRAY 1 
N1 

N2 


ARRAY2 


Byte count. 

Array containing bytes to be moved. 

First byte position in ARRAY1 to be moved (NT= 1). 
First byte position in ARRAY2 to receive data (N2> 1). 


Destination array. 


Byte indices start at 1. 


MVBYTT(CNT,ARRAY1,N1,ARRAY2,N2) 


Moves bytes (or characters) from one array to another. 


CNT 
ARRAY1 
N1 
N2 


ARRAY2 


Byte count. 

Array containing bytes to be moved. 

First byte position in ARRAY1 to be moved (N1= 0). 
First byte position in ARRAY2 to receive data (N2=> 0). 


Array receiving bytes. 


Byte indices start at 0. 
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NXTCHAR(SWT) 


Accesses next character to be scanned, outputs the character type, and 
sets up scan globals. 


SWT Switch controls screening of blanks and case conversion: 
0 Access next character, converts lower to upper case. 
1 Access next non-blank character, converts lower to upper 
case. 
2 Access next non-blank character — no case conversion. 
3 Access next character — no case conversion. 


e System overlay global CHAR: 


Next character, in character format. If there are no more characters in 
the array, zero is Output. 


e System overlay global CHARTYP: 


Output 


1 
2 
3 


Character Type 


Alphabetic or ampersand (&). 
Number. 
Special character, or end of array. 


e INITCHAR and NXTCHAR set up character string and system globals 
for scan routines. 


e The two routines are automatically called to set up scanning of the 
command line. They must be explicitly called to initialize scanning of any 
other stream of characters (i.e., a line input with TYPIN). 
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NXTFPG(ARRAY, IND, SIZE, OPTIONS) 
Accesses the next page of a file that has been initialized with PAGFIL. 
ARRAY The eight-word array used for paging this file. 
OPTIONS Same as in FREAD. 
IND 0 This is not last page. 
—1_ This is last page. 


1 Last page already returned. 
SIZE Number of words on the page. 


NXTNAM(NMLST,NINFO,NMBYT,BYTCT) 


In a scan initialized with INITNM, NXTNAM gets the next name from the 
name list. 


NMLST Same form used in INITNM. 
NINFO: Same form used in INITNM. 
NMBYT Byte number in NMLST(2) where name starts. 
BYTCT Byte count of the name. 
0 Not the last name in the list. 
1 The last name in the list. 
—1 There are no more names in the list. 
NXTNAM is part of a package that includes FMNLST and INITNM. Call 


FMNLST to get the list of names, and then call INITNM and NXTNAM to 
get individual names from the list. 
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OCTBCD(OCT, TXT) 
Converts an integer to an octal text string. 
OCT Integer for conversion. 


TXT Three-word array receiving the octal text string (six characters 
are always returned). 


OREAD(CHANNEL, DLOC, COUNT, BUF, OPTIONS) 


Reads an overlay into memory. If there is already an overlay in memory, it 
will overwrite. 


e All arguments are the same as FREAD, see FREAD for further 
documentation. 


e Use OREAD with the Trace or Debug options of the loader. 
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PAGFIL (CHANNO,DLOC,SECTORS, BUFFER, PAGSIZ, ARRAY) | 
Initialize file paging so that a file opened for read may be paged. 
CHANNO The channel number of the open file. 

DLOC Starting disc location (two WORDS, as in FREAD). 


SECTORS Number of sectors to be paged (two words). 


BUFFER Buffer into which file is to be paged. 
PAGSIZ Size of the pages in sectors (< BUFFER size in sectors). 
ARRAY Eight-word array used to page file. 
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PERROR(ERROR, FILENAME,LEVEL) 

Prints an error message, given an error number and a text file of messages. 
ERROR Error number. 

FILENAME Filename in FMNAME format or zero if there is no file. 


LEVEL Error level: 


—1 User selectable default. See the SELECT ERRLEVEL 
command in the CGOS 200 GNA Operator Guide. 
0 Print the error number only. 
1 Print the error number and the short message. 
2 Print the error number and the long message. 
3 Print the short message only. 
4 Print the long message only. 


e Error messages are referenced in text files. The first file searched is sup- 
plied by the caller (argument FILENAME). If no message is found there, 
the system files are checked. (The system files are: 
SYSNEWS.ERROR/FM,SYS.) 

e The error message has three parts: 

1. A hex number (printed when LEVEL is 0, 1, or 2). The format is: 
**ERROR CALL xxxx** 

2. A short message, printed if LEVEL is not 0. 

3. Text that is printed if LEVEL is 2 or 4. 


Message text file as follows: 


The first line is six characters long and contains the hex error number. The 
format is: 


= = XXXX 
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The lines that follow constitute the message, which is terminated: by a 
line starting with “= =". 


There are two varieties of message lines. Lines that begin with ‘’--” are part 
of the short message. All other lines are part of the long message. 


e Short and long message lines may occur in any order. 


e For an example of a message text file, see SYSNEWS.ERROR.SYS. 
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PNCHLDR(CNT) 
Punches a leader on paper tape unit. 
CNT Number of blanks (no holes). 


Each blank occupies one frame = 1/10th inch. 


POP(P,WORD) 

Removes a word from the top of a push-down list. 
P Push-down list. 

WORD Word removed. 


Word removed. 


See IPDL, PUSH. 
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POPN(P,CNT,ARR) 


Removes a block of words from a push-down list. 


P Push-down list. 
CNT Number words to remove. 
ARR Words removed from push-down list. 


See IPDL, PUSHN. 


PPT(CNT,ARR) 

Outputs data to punch paper tape unit (PPTDEV). 
CNT Word Count. 

ARR Array of words output to PPTDEV. 
“FOOE’x No PPTDEV assigned. 


The left half of a word is punched first. 


PPT1 
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PPT1 
SYNTAX PPT1(CHAR) 
PURPOSE Outputs one character to PPTDEV, if PPTDEV is assigned. 
INPUT | CHAR Character to be output, in byte format. 
ERRORS ‘FOOE’x = No PPTDEV assigned. 
PPTN 
SYNTAX PPTN(CNT,ARR) 
PURPOSE Outputs a string of bytes to PPTDEV. 
INPUT CNT Number of bytes to be output. 
ARR Byte string packed two bytes per word — starting in left 
byte of first word. 
ERRORS ‘FOOE’x = No PPTDEV assigned. 
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PUSH(P,WORD) 
Adds a single precision integer to the top of a push-down list. 
P Push-down list 
WORD Word to add. 


See IPDL, POP. 


PUSHN(P,CNT,ARR) 

Adds a block of words to a push-down list. 
P Push-down list. 

CNT Number of words to add. 

ARR Words to add. 


see IPDL, POPN. 


PUTBIT(VALUE,STRING, INDEX) 


Turns a bit ON or OFF. 


VALUE 0 Bit OFF, otherwise bit is ON. 
STRING Bit string array. 
INDEX Bit index into STRING (leftmost bit is 0). 
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The PUTFILE utility package is used to access text files on a line-by-line 
basis. The normal sequence for reading from a text file would be open with 
PUTFILE, read lines of text with PUTLINE or PUTLINEB, and close with 
PUTCLOSE, PUTCLEAR, and PUTABORT. 


PUTFILE(FSB,BUF, BUFSIZ, FNAME,OPTIONS) 


Opens a text file for output on a line-by-line basis. 


FSB File Status Block (eight words, see below) FSB(1) MUST be 
set to 1. 
BUF Output Buffer. 


BUFSIZ Length of buffer in sectors. 
FNAME _ Filename (without the &BCD) in the form returned by FNAME: 


Word 1 Character count (includes !). 
Word 2-n Filename (includes !). 


OPTIONS Bit-oriented options: 


Bit (Leftmost bit is 0.) 
7 ON Create new catalogs as required. 
OFF Give error if any catalog missing. 
15 ON Function returns errors. 
OFF Errors go to System error routine. 


Description of FSB (File Status Block): 


FSB(1) Status: © 1 No file open. 
12 File open. 
13 File open without BUF in memory. 
FSB(2) Output channel number. 
FSB(3-4) Relative DLOC in file. 
FSB(5) Byte counter. 
FSB(6) Old line count. 
FSB(7) Number of words in buffer. 


FSB(8) Running CHECKSUM for the output line. 
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~ OPTIONS(1) bit 15 ON: 


0 Indicates no error. 
FLAG  _ Indicates type of FILE MANAGER ERROR. 


For description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


None of the PUTFILE routines have local variables to maintain. Only the 
integrity of FSB and BUF Is important. 


e BUFSIZ is a multiple of SECTSIZ that cannot exceed 32K bytes (16384 
words). | 


e BUFSIZ must remain constant during the writing of the text file. 


However, these routines can be used to write two files at the same time, 
using a BUFSIZ of two sectors for one file and five sectors for the other. 


PUTLINE(FSB,BUF,LEN,LINE) 

Adds a line to the text file opened by PUTFILE. 
FSB _ File Status Block. 

BUF Disc buffer. 

LEN Length of the character string in LINE. 
LINE Character string. 


e Additional documentation, including a description of the FSB (File 
Status Block), may be found under PUTFILE. 


e This routine must operate in conjunction with PUTFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. | 
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PUTLINEB(FSB,BUF,LEN,LINE,OFFSET) 


Adds a line to the text file opened by PUTFILE. Equivalent to PUTLINE 
with an added byte offset. 


FSB File Status Block. 

BUF Disc buffer. 

LEN Length of the character string in LINE. 
LINE Character string. 


OFFSET Byte offset in LINE (counted from 0) where the string of LEN 
bytes will be written. 


e Additional documentation, including a description of the FSB (File 
Status Block), may be found under PUTFILE. 


e This routine must operate in conjunction with PUTFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 
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PUTABORT(FSB, BUF) 

Aborts the text file being written by PUTFILE. 
FSB File Status Block. 

BUF Disc buffer. 


¢ Complete documentation, including a full description of the FSB (File 
‘Status Block), may be found under PUTFILE. 


e This routine must operate in conjunction with PUTFILE. 


Fora description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. | 


PUTCLEAR(FSB, BUF) 

Marks the FSB (File Status Block) of an open file to indicate that the text 
file buffer is no longer available and must be loaded into memory the next 
time PUTLINE is called. | 

FSB File Status Block. 

BUF Disc buffer. 


e Additional documentation, including a description of the FSB (File 
Status Block), may be found under PUTFILE. 


e This routine must operate in conjunction with PUTFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 


PUTFILE 
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PUTCLOSE 
SYNTAX PUTCLOSE(FSB, BUF) 
PURPOSE Closes the text file being written by PUTFILE. 
INPUT FSB ‘File Status Block (see PUTFILE). 
BUF _ Disc buffer. 
NOTES e Additional documentation, including a description of the FSB (File 
Status Block), may be found under PUTFILE. 
e This routine must operate in conjunction with PUTFILE. 
ERRORS For a description of FILE MANAGER ERRORS, refer to: 


SYSNEWS.ERROR.FM 
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PUTFLD(VALUE,STRING,FBIT,SIZE) | 
Puts a specific value into one field of a bit string. 


VALUE Integer value to be stored. Only the low order (rightmost) 
bits are used. 


STRING Bit string to store VALUE. 

FBIT Location of field where VALUE will be stored. Location is 
specified by the displacement between the high-order (left 
most) bit of the field and the high-order bit of string. 

SIZE Size of target field in bits (0 < SIZE < 17). 


Side effects of changing STRING or any error call due to inconsistent 
arguments. 


The change to STRING can be characterized in two ways: 
@ GTFLD.(STRING,FBIT,SIZE) will return VALUE. 


e For |=1,SIZE, STRING (FBIT+I—1) will equal value (15-SIZE + |) 
when STRING and VALUE are assumed to be bit vectors. 
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PUTLABEL(TBLABEL,SAVLABEL) 


Puts the label saved in SAVLABEL back into the requested system label 
spot in the TASKBLOCK. | 


TBLABEL 


SAVLABEL 


Identifies the desired system label to put into the 
TASKBLOCK: 


—1 TAPERLBL 
—2 SYSERLBL 
—3 INTROQUIT 


Two-word array for the label output by GETLABEL, or a 
local label created by calling LBLSET. 


‘FOOD’X — TBLABEL specified is illegal (bad arg). 


e For safety, PUTLABEL should only be used in the user address space. 


e See also, GETLABEL, LBLGO, LBLSET, and RESETLBL. 
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The general sequence for reading bytes from a binary sequential file would 
be to open with READBEFIL, read bytes with READBYTE, and close with 
READCLS. , 


READBFIL(FSB,BUF,BUFSIZ, FNAME,OPTIONS) 


Opens binary sequential file for input. 


FSB(11) 


BUF(255) 
BUFSIZ 


FNAME 


File Status Block; 
FSB(1) must be set to one. 


Disc buffer. 
Size of disc buffer in sectors. 
Filename in the form returned by FMNAME: 


Word 1 | Character count (includes !). 


Word 2-n __ Filename (includes !). 


OPTIONS(1) 


Bit 
0 


14 


15 


ON 


ON 


ON 


OFF 


(Leftmost bit is 0.) 


Return extended file information array in 
OPTIONS(2-16). 


Return normal file information array in OPTIONS(2-5). 


Error condition results in error FLAG returned as a func- 
tion name. 


Error condition results in the call ERROR(FLAG). 
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OPTIONS(1) bit 14 OFF: 


(Word) Normal Array 
(2-3) Disc location, always (0,0). 
(4-5) Total sector count of file, 


OPTIONS(1) bit 14 ON: 


(Word) Extended Array. 
(2-3) Disc location, always (0,0). 
(4-5) Total sector count of file. 
(6) Creation date. 
(7) Time of day of creation in one-second inter- 
vals. 
(8) Access date. 
(9) File protection group: 
Bit (Leftmost bit is 0.) 
0-7 | Reserved. 
8-15 File protection group. 
(10) File status, with bit ON: 
Bit (Leftmost bit is 0.) 
In use. 
1 Opened for modify in place. 
2 To be deleted when closed if use count is 0 


(i.e. old file of create with supersede). 
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(11) 


(12) 


(13) 
(14) 
(15) 


(16) 
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— 
ol 
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Opened for create. 

Temporary entry for create with supersede. 
Opened for regular read. 

Reserved. 

File is a catalog. 

File is a volume. 

Reserved. | 


Number of users currently accessing file or 
included file — incremented each time the 
file or included file is opened, decremented 
each time it is closed. 


Contiguous data flag: 
All data allocated contiguously. 


Data not contiguous, N is sector count (N 
>0) of first contiguous chunk of the file (if 
file has QO length this is indicated by 
ARRAY (3-4)). 


User-defined attribute value. 
User-defined attribute value. 
CHKSUM. 


File type. 
(Leftmost bit is 0.) 


Not task protected. 

1 + number of task which has protected 
the file. | 
Not defined. 

Catalog. 

Object. 

Text. 

Configuration. 

Reserved. 

PEP object code. 

Core image (overlay). 

Command table. 

Loader data file (symbol table or library). 


\ 
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A Reserved. 
B Accounting table. 
E Reserved. 
F 280 binary files. 
10-1F Reserved for CGOS. 
20 CADDS 4 part files. 
21 CADDS 4 TVF files. 
22 CADDS 4 figure files. 
23-2F Reserved for CADDS 4. 
30-AF Unused. 
BO-BF Reserved for batch files. 
CO-FE Unused. 
FF Work files (deleted on FMCLEAR). 
OPTIONS(1) bit 15 ON: 
0 Indicates no error. 


FLAG Indicates type of FILE MANAGER ERROR. 


Refer to ERROR. For description of FILE MANAGER ERRORS. 
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READBYTE(FSB,BUF,COUNT,BLOCK,OFFSET,ACTUAL) 
Retrieves the next block of bytes from a binary sequential file. 
FSB File Status Block. 

BUF | Disc buffer. 

COUNT Number of bytes to read. 
OFFSET Byte offset in output block. 

ACTUAL ~~ Actual number of bytes transferred. 

BLOCK Block of bytes. 


This routine must operate in conjunction with READBEFIL. 


READBCLS(FSB,BUF) 

Closes the input channel of a binary sequential file. 
FSB File Status Block. 

BUF Disc buffer. 


This routine must operate in conjunction with FM.READBFIL, Additional 
documentation can be found under READBFIL. 


THE READFILE 
UTILITY 
PACKAGE 


READFILE 


SYNTAX 


PURPOSE 


INPUT 
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The general sequence for reading a binary sequential file would 
be to open with READFILE, read blocks of words with READBLOK or 
READSECT, and close with READCLOS. 


These four routines can also be used to read a random access file. There 
are three additional functions for manipulating the sequential access 
pointer of a random access file. A call to READMARK reads the position of 


the pointer, while READPOS and READTOP can be used to move the 
pointer. 


READFILE(FSB, BUF,BUFSIZ, FNAME,OPTIONS) 

Opens a binary sequential file for reading. 

FSB(11) File Status Block, FSB(1) must be set to one before calling 
READFILE. After a call to READCLOS, the value of FSB(1) 
will also be one. In the interim, FSB may not be read or 
changed. 

BUF(255) Disc buffer. 

BUFSIZ Size of disc buffer in sectors. 


FNAME Filename in FM name format: 


Word 1 Character count (includes !). 
Word 2-n Filename (includes !). 


OPTIONS(1) 

Bit (Leftmost bit is 0.) 

0 ON Return extended file information array in 
OPTIONS(2-16). 

14 ON Return normal file information array in 
OPTIONS(2-5). 

15 ON Error condition results in error FLAG returned 
as a function name. 

OFF Error condition results in the call 


ERROR(FLAG). 
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OUTPUT OPTIONS(1) bit 14 ON: 
(Word) Normal Array. 
(2-3) | Disc location, always (0,0). 
(4-5) Total sector count of file. 


OPTIONS(1) bit 14 OFF: 


(Word) Extended Array. 
(2-3) Disc location, always (0,0). 
(4-5) Total sector count of file. 
(6) | Creation date. 
(7) | | Time of day of creation in one-second 
intervals. 
(8) Access date. 
(9) File protection group. 
Bit (Leftmost bit is 0.) 
0-7 Reserved. 
8-15 File protection group. 
(10) File status, with bit ON: 
Bit (Leftmost bit is 0.) 
In use. 
1 Opened for modify in place. 
2 To be deleted when closed if use count is 0 


(i.e., old file of create with supersede). 
Opened for create. 
Temporary entry for create with supersede. 
Opened for regular read. 
Reserved. 
File is a catalog. 
File is a volume. 
-15 Reserved. 


OO oOn DD OF P W 
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(11) 


(12) 


Bit 


0-7 


8-15 


V oil 
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mm 0 


10-1F 


S38 


Number of users currently accessing file or 
included file — incremented each time the 
file or included file is opened, decremented 
each time it is closed. 


Contiguous data flag: 
All data allocated contiguously. 


Data not contiguous, N is sector count 
(N 0) of first contiguous chunk of the file 
(if file has O length this is indicated by 
ARRAY(3-4)). 


User-defined attribute value. 
User-defined attribute value. 
CHKSUM. 


File type 
(Leftmost bit is 0.) 


Not task protected. 
1 + number of task which has protected 
the file. 


Not defined. 

Catalog. 

Object. 

Text. 

Configuration. 
Reserved. 

PEP object code. 
Core image (overlay). 
Command table. 
Loader data file (symbol table or library). 
Reserved. 
Accounting table. 
Reserved. 

Z80 binary files. 
Reserved for CGOS. 
CADDS 4 part files. 
CADDS 4 TVF files. 
CADDS 4 figure files. 
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OPTIONS(1) bit 15 ON: 


Reserved for CADDS 4. 

Unused. 

Reserved for batch files. 

Unused. 

Work files (deleted on FMCLEAR). 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


Refer to ERROR for description of FILE MANAGER ERRORS. 
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READBLOK(FSB,BUF,COUNT,BLOCK) 

Retrieves the next block of words from a binary sequential file. 
FSB File Status Block. 

BUF Disc buffer. 

COUNT Number of words to read. 

BLOCK Block of words. 


This routine should operate in conjunction with READFILE. ellie 
documentation can be found there. 


READSECT(FSB,DLOC, COUNT, BLOCK) 


Reads a block of words from a file opened for sequential word access. The 
block begins on a sector boundary specified by the user. 


FSB File Status Block. 

DLOC Disc location to begin reading from. 

COUNT Number of words to read. 

BLOCK Block of words. 

This routine must be used in conjunction with READFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM 


9-139 


READFILE 
READCLOS 


READCLOS 
SYNTAX 
PURPOSE 


INPUT 


NOTE 


READMARK 


SYNTAX | 


PURPOSE 


INPUT | 


OUTPUT 


NOTE 
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READCLOS(FSB, BUF) 

Closes the channel of a binary sequential file. 
FSB File Status Block. 

BUF Disc buffer. 


This routine must operate in conjunction with READFILE. 


READMARK(FSB,BUF,WORD) 

Returns the current position in a sequential binary file. 
FSB File Status Block. 

BUF Disc buffer. 

WORD _ Double integer indicating position of next word in file. 


This routine should be used in conjunction with READFILE. 
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READPOS(FSB,BUF,DLOC, INDEX) 

Sets the sequential access pointer to a new disc location and sector index. 
FSB File Status Block. 

BUF Disc buffer. 

DLOC Disc location to read from. 

INDEX Sector index to read from. 

This routine must be used in conjunction with READFILE. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM 


READTOP(FSB,BUF) 

Moves sequential access pointer to beginning of file. 
FSB File Status Block (see READFILE). 

BUF File buffer (see READFILE). 


READTOP is part of the READFILE utility and must be used in conjunction 
with READFILE. 
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RENAME(OLDNAME, NEWNAME, OPTIONS, SPECFIR) 


e Renames lowest level catalog or filename (delete/write access). 


© Changes file protection group (change access). Changes user attribute 
(write access). 


e Returns a value to indicate that file exists; called through FILEXS — 
exclusive operation (read access). 


e Assigns or deassigns task protection — no other bits (read access) can 


be set. 


e Returns SRCHFIL or file entry ARRAY (read access), file must not be in 
use on any OPTION except unassigning task protection. 


OLDNAME 
NEWNAME 
OPTIONS(1) 
Bit 
0 ON 
1 ON 
2-3 
4 ON 
5 ON 


Full ASCII filename with a (.) as the delimiter between 
components and an (!) following the last character. Each 
component of the filename must be 20 characters or less. 
New ASCII filename, to replace the rightmost component 
of the OLDNAME. The name must be 20 characters or 


less, excluding the (!), which follows the last character 
and terminates the string. 


(Leftmost bit is 0.) 

Change rightmost component to NEWNAME. 

Change the file protection group to value in SPECIFR(1). 
Reserved (must be zero). 

Change user attribute value to SPECIFR(4-5). 


F,N first word of SRCHFIL ARRAY (ignore other bits in 
OPTIONS(1) except 15). 


INPUT 
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15 


ON 


ON 


ON 


ON 


ON 


ON 
OFF 


ON 


ON 


OFF 


Note 
Options for bits 6 and 7 are reserved for 
system use only. 
Return SRCHFIL ARRAY (has precedence over bit 7) 
also F,N as bit 5 OPTIONS(1). 


Return file entry ARRAY (if bit 6 is OFF) also F,N as bit 5, 
OPTIONS(1). | 


Return total file size (= -1 tf entry is a volume) also F,N as 
bit 5, OPTIONS(1). 


Reserved (must be zero). 

Assign task protection. No effect if: 
Any of bits 0-9,11-14 are also on. 
File is already task protected. 


File is in use (gives error C017). 
File is access protected (gives error C012). 


oo F ® 


Unassign task protection. No effect if: 


Any of bits 0-10,12-14 also ON. 

File not task protected. 

If task protected but not by this task. 
File is access protected (give error C012). 


207m 


Reserved (must be zero). 


OPTIONS(2) contains additional options data. 
OPTIONS(2) ignored. ; 


Return working directory name count in OPTIONS(3) 
followed by characters named in OPTIONS(4-42). If 
working directory not enabled, value is returned in 
OPTIONS(3). 


Error condition results in error FLAG returned as function 
name. | 


Error condition results in the call 
ERROR(FLAG). 
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INPUT | OPTIONS(2) 


(Continued) 
Bit (Leftmost bit is 0.) 
0-15 Reserved (must be zero). 
SPECIFR(1) New file protection group. 
(4-5) New value of user attribute. 

OUTPUT OPTIONS(1) bit 14 ON: 

OPTIONS(3) Directory name character count or < 0 if working 
directory not enabled. 

OPTIONS(4-42) Directory name for OPTIONS(3) noinber of 


OPTIONS(1) bit 6 ON: 


SPECIFR(Word) 
(1) =-3 
=-2 
=-1 
= 0 
> 0 
(2-3) 
(4} 
(5-6) 
(7) 


5-144 


characters 


SRCHFIL ARRAY 


Entry is a volume. 

Entry is a catalog. 

Entry found — not a catalog. 

File not found in parent catalog. 

Catalog in complete filename does not exist. Value 
is level number of first catalog that did not exist 
(1=leftmost catalog in filename string). 


DLOC of file entry sector. 
Index into file entry sector. 
DLOC of parent catalog sector. 


Index into parent catalog sector. 
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OPTIONS(1) bit 7 ON: 


SPECIFR(1-25) File entry array. 
SPECIFR(26-27) Volume DLOC (includes unit and drive). 


OPTIONS(1) bit 8 ON: 
SPECIFR(1-2) Total file size or —1 for volume. 
If OPTIONS(1) bit 15 is set: 


0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


For a description of FILE MANAGER ERRORS, refer to: 
SYSNEWS.ERROR.FM. 
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RESETLBL(TBLABEL) 

Resets requested system label to the task default value specified in 
SYSOV.NEXTCOMM. The label is assigned this value when a new com- 
mand is issued; the value may be changed with LBLSET or PUTLABEL. 


TBLABEL Label to be reset: 


—1 TAPERLBL 
—2 SYSERLBL 
—3 INTRQUIT 


‘FOOD’x TBLABEL specified is illegal (bad arg). 


e For safety, RESETLBL should only be used in the user address 
space. 


° See also, GETLABEL, PUTLABEL, LBLGO, and LBLSET. 


RETERR(ERRNUM) 


Returns latest system error number after a call to ERROR has forced a 
LBLGO(SYSERLBL). 


ERRNUM _ System error number. 


System error number. 
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ROPEN(CHANNEL, FILENAME, OPTIONS, ARRAY) 


Opens a file to be read. 


FILENAME 


(Word) 


(1-41) 


(42-43) 


(44) 


OPTIONS(1) 


Bit 


0 


ON 
OFF 


ON 


OFF 


Note 


Read access Is necessary. File cannot be open 
for modify. 


Full ASCII filename with a period (.) between com- 
ponents and an exclamation mark (!) following the 
last character. Each component of the filename 
must be 20 characters or less. 

DLOC of file entry sector. 


Index of file entry. 


(Leftmost bit is 0.) 


Return extended file information array. 


Return normal file information array. 


No-search option enabled. FILENAME (41-43) con- 
tains DLOC and index including volume info for file 
entry. 


Note 


This option is reserved for system use only. 


No-search-option disabled. 


Reserved (must be zero). 
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2-12 
13. ON 
OFF 
14 ON 
15. OFF 
OPTIONS(2) 
Bit 
0-15 


Reserved (must be zero). 


OPTIONS(2) contains additional option data. 
OPTIONS(2) ignored. 


Return working directory name count in 
OPTIONS(3), followed by name _ characters in 
OPTIONS(4-42). If working directory disabled, value 
is returned in OPTIONS(3). 


Error condition results in the call ERROR(FLAG). 


(Leftmost bit is 0.) 


Reserved (must be zero). 


OPTIONS(1) bit 14 ON: 


OPTIONS(3) 
OPTIONS (4-42) 


ARRAY (Word) 
OPTIONS(1) 
(1-2) 

(3-4) 
_ OPTIONS(1) 
(1-2) 
(3-4) 
(5) 
(6) 


(7) 


Directory name character count or <0 if working 
directory not enabled. 


Directory name _ for OPTIONS(3) number of 
characters. 


File information array. 

Bit 0 OFF — Normal Array. 
Disc location, always (0,0). 
Total sector count of file. 

Bit 0 ON — Extended Array. 
Disc location, always (0,0). 
Total sector count of file. 
Creation date. 


Time of day of creation in one-second intervals. 


Access date. 


ROPEN 
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OUTPUT (8) File protection group. 
(Continued) 
Bit (Leftmost bit is 0.) 
Q-7 Reserved. 
8-15 File protection group. 
(9) File status, with bit ON: 
Bit (Leftmost bit is 0.) 
0 In use. 
1 Opened for modify in place. 
2 To be deleted when closed if use count is 0 (i.e., old 


file of create with supersede). 
Opened for create. 
Temporary entry for create with supersede. 
Opened for regular read. 
Reserved. 
File is a catalog. 
| File is a volume. 
-15 Reserved. 


OO on SD OF f OD 


(10) Number of users currently accessing file or included 
file — incremented each time the file or included file 
is opened, decremented each time it is closed. 

(11) Contiguous data flag: 

0 All data allocated contiguously. 

N Data not contiguous, N is sector count (N > OQ) of 
first contiguous chunk of the file (if file has 0 length 
this is indicated by ARRAY(3-4)). 

~ (12) User-defined attribute value. 


(13) User-defined attribute value. 


(14) CHKSUM 
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OUTPUT (15) File type: 
(Continued) 
Bit (Leftmost bit is 0.) 
0-7 =0 Not task protected. 
< 0 1 + number of task which has protected 
the file. 

8-15 0 Not defined. 
1 Catalog. 
2 Object. 
3 Text. 
4 Configuration. 
5 Reserved. 
6 PEP object code... 
7 _ Core image (overlay). 
8 Command table. 
9 | oader data file (symbol table or library). 
A Reserved. 
B Accounting table. 

C-E Reserved. 
F Z80 binary files. 
10-1F Reserved for CGOS. 


20 CADDS 4 part files. 
21 CADDS 4 TVF files. 
22 CADDS 4 figure files. 
23-2F Reserved for CADDS 4. 
30-AF Unused. 
BO-BF — Reserved for batch files. 
CO-FE Unused. 
FF Work files (deleted on FMCLEAR). 


CHANNEL Channel number assigned to the file. 
FUNCTION OPTIONS(1) bit 15 ON: 
RETURN 
0 Indicates no error. 
FLAG Indicates type of FILE MANAGER ERROR. 


ERRORS Refer to ERROR for description of FILE MANAGER ERRORS. 
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RPT(SWT,CNT,ARR) 


Inputs data from read paper tape unit (RPTDEV). 


SWT 0 Read tape from first (current) character without skipping 
leader. First character goes in left byte of first word. 
1 Read tape from first non-blank character skip leader. First 
character goes in right byte of first word; left byte = ‘00’x. 
2 Read tape from first non-blank character skip leader. First 
character goes in left byte of first word. 
CNT Word count (number of words to be filled). 
ARR Array receiving the data. 
‘FOOE’x No RPTDEV assigned. 
RPT1(CHAR) 


Inputs one character from RPTDEV, if RPTDEV is assigned. 


CHAR 


“FOOE’x = 


Character input, in byte format. 


No RPTDEV assigned. 
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RPTN(CNT, ARR) 


Inputs bytes from RPTDEV. 


CNT 


ARR 


‘FOOE’X = 


Number of bytes to input. 


Array containing bytes input, packed one per right byte of 
word. 


No RPTDEV assigned. 
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SELESORT(ARRAY,N, COMPFUN) 


Sorts an internal file of one-word records. The comparison of keys is per- 
formed by a user-supplied function. 


ARRAY Internal file of one-word records. 
N Number of records in file. 


COMPFUN _ Record comparison function with a return that depends on 
the relation of KEY1 and KEY2: 


KEY? COMPFUN 
< KEY2 <0 
= KEY2 = 0 
> KEY2 > 0 
ARRAY Sorted internal file. 


Method: 


Knuth, Donald E., 7he Art of mOrneees Programming, First Edition, 
Section 5. 


Modified for TPL (arrays start at subscript 0): 


S71 (LOOP ON J) PERFORM STEPS S2 AND S3 FOR 

J=N,N-1,...0. 

32 (FIND MAX (K1,...,KJ) SEARCH THRU KEYS KJ,KJ-1,K1 

TO FIND A MAXIMAL ONE; LET IT BE KI. 

$3 (EXCHANGE WITH RJ) INTERCHANGE RECORDS RI< = = >RJ. 
(NOW RECORDS R4J,...,RN ARE THEIR FINAL POSITION. 
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SETBIT 
SYNTAX | SETBIT(STRING, INDEX) 
PURPOSE ‘Turns on a specified bit in a bit string. 
INPUT STRING Bit string array. 
INDEX Bit STRING number (leftmost bit is 0). 
SETBREAK 
SYNTAX SETBREAK 
PURPOSE Instructs CHKINTR, CHKQUIT, and CHKSTOP to set a flag to be tested 
by CHECKBREAK instead of executing an LBLGO.(INTQUIT). 
NOTE See CHKBREAK. 
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SETCOM(LEN,STRING,IPOS) 


Inserts a string in the task command buffer. To view the string, use a task 
option to STATUS. 


LEN Length of the string. 
STRING String to be inserted. 
IPOS Buffer location for inserting STRING. 
Note 
If STRING is too long for the command buffer, 


characters will be inserted until the length 
limitation is exceeded. 


String inserted into the command buffer. 
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SETPG(BUFFER,SPID,PERMIT) 


Modifies a page slot of the user’s page frame. The user specifies a new 
page and the permitted access for the page slot. 


BUFFER Memory buffer: 


e One memory page long (‘800’x words). 
e Aligned on a page boundary. 


System Page ID of the page to put into the slot specified by BUFFER. If 
SPID is NULL, the new slot will be empty. 


PERMIT Type of access for the page slot identified by BUFFER: 
P&RW Any access is legal. 


P&RO Read-only. 
P&NO No legal access. 


0 No errors. 

E010 BUFFER its not aligned on a page boundary. 

E020 [legal system page identifier (SPID). 

E050 PERMIT allows reading or writing the page, but SPID spec- 
ifies the NULL SPID. 

E051 The page specified by SPID is protected and cannot be 
accessed in the manner requested by PERMIT. 

EO60 Illegal protection attribute (PERMIT). 

E110 Cannot modify O/S page slot. 


e The symbolic constants are defined in SYM.EQU.MEMMAN and 
SYM.EQUF.MEMMAN. 


e The caller must have logical access to the memory page specified by 

~ SPID. If the caller owns the page, the owner protection attributes must 
allow the access requested by PERMIT. Otherwise, the public protection 
attributes must allow access requested by PERMIT. O/S page slots may 
not be modified. 
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SETPGP(SPID,PROT) 

Modifies the parameters of a system page. 

SPID System Page ID of a memory page. 

PROT Desired protection attributes: 
P&RW Any access is legal. 


P&RO Read-only. 
P&NO No legal access. 


SETPGP 


0 No errors. 

E020 Illegal system page identifier (SPID). 

E024 Calling task does not own the page specified by SPID. 
E060 Illegal protection attribute (PROT). 


The symbolic constants are defined in SYM.EQU.MEMMAN and 


SYM.EQUF.MEMMAN. 
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SETPUNCH(VALUE) 
Sets the parity option for the task PPTDEV. 


VALUE Possible parity OPTIONS: 


0 No parity, transparent data transfer. 

1 Odd parity. 

2 Even parity. 

3 Mark — MSB of byte always set to 1. 
4 Space — MSB of byte always set to 0. 
0 No errors. 

1. Not used. | 
2. Unit number is not valid. 

3 Unit cannot be a PPTDEV. 

4 Value is not in range 0-4. 

5 Unit not declared PPTDEV. 
SETSTRG(STRING) 


Copies eight characters into the task global TSKUSTRG. 
STRING Eight-byte string to be stored in TSKUSTRG. 


STRING is moved into the task global TSKUSTRG. 
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SHELSRTN(RECS,NREC, COMPFUN,RECLEN, REC) 

Sorts records with a shell sort. Timing tests show that SHELSRTN is the 
fastest general sort for an array of 15 to 1500 multiword records. It is not 
stable, however. For a stable sort, use INSESRTN. 

RECS Array containing data to be sorted. 


NREC Number of records. 


COMPFUN _ Record comparison function with a return that depends on 
the relation of KEY1 and KEY2: 


KEY? | COMPFUN 
< KEY2 <Q 
= KEY2 = 0 
> KEY2 > 0 


RECLEN Length of record (in words). 

REC Caller supplied scratch, RECLEN words long. 

Array RECS is sorted. 

The sorting method is described in Knuth, Vol.3, pg. 85. SHELSRTN uses 


the increments suggested at the bottom of p.95. Comments of the form 
‘DN’ reflect the algorithmic steps outlined on p.85. 
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SNGL(F) 
Converts double precision real to real. 
F Double precision real. 


Single precision real. 


SRTESTIO(IOFLAG, ERRNO) 
Tests an IOFLAG for completion of no-wait I/O. 
IOFLAG Flag returned by an |/O request call. 
‘ERRNO __ Error value returned by the |/O system. 
0 1/0 not done. | 
—1 1/OFLAG is bad or flag was not assigned to a request 


1 1/0 done and flag released, or no IOFLAG’s for request 


e If the FUNCTION RETURN is zero, SRTESTIO should be called again 
later. 


e ERRNO value is not valid with an |/O request in progress (FUNCTION 
RETURN = 0). 
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SRWAITIO(IOFLAG, ERRNO) 

Changes a NOWAIT I/O request into a WAIT I/O request. 
lOFLAG Address of a valid |OFLAG. 

ERRNO Error value generated by the I/O system. 


SRWAITIO resets the IOFLAG value. This eliminates the need for calling 
TESTIO.(IOFLAG). 


STBYTF(WORD,ARRAY,N) 

Stores a byte (FORTRAN version). 

WORD Word containing byte, in byte format. 
N Byte position in the array (N= 1). 
ARRAY Array receiving the byte. 


Byte indices start at 1. 
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STBYTT(WORD,ARRAY,N) 

Stores a byte (TPL version). 

WORD | Word containing byte, in byte format. 
ON — Byte position in the array (N= 0). 

ARRAY Array receiving the byte. 


Byte indices start at 0. 


STCHRF(WORD,ARRAY,N) 
Stores a character (FORTRAN version). 
WORD Word containing character, in character format. 
N Byte position in the say (N= 1). 
ARRAY Array receiving WORD. 


Byte indices start at 1. 


STCHRT(WORD,ARRAY,N) 
WORD Word containing character in character format. 
N Byte position in the array (N= 1). 


ARRAY Array receiving WORD. 


Byte indices start at 0. 
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STYPEOK(FILENAME, MESSG1,MESSG2) 


Checks for OK response to a message printed on the COMDEV. The 
response must also come from the COMDEV. 


FILENAME 


MESSG1 


MESSG2 


0 
—1 


Note 
If the response is QUIT, then STYPEOK does a 
LBLGO to —3 —. This is identical to an INTR- 
QUIT <ESC>Q. 
Filename in standard FMNAME format, or a third message. 


First message: 


(1) Character count. 
(2-n) Message characters. 


Question asked: TYPE OK TO MESSG2: 


(1) Character count. 
(2-n) Message characters. 


Response was OK. 
No OK response. | 


If a third message is used and the final character in the message is an 
exclamation mark (!), the (!) will not be printed (as in a filename). 
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STYPIN(MAX,BUF,CNT,LCFLAG,ECHO,EXFLAG) 
Inputs a sequence of characters from the COMDEV or an execute file. 
MAX Maximum number of characters. 
LCFLAG Lower case flag: 
0 Lower case is accepted. 
1 Lower case converted to upper case. 
—1 Use default (set by SELECT command). 
ECHO Echoing flag: 
0 Echo all characters normally. 
1 Echo all characters as spaces. 
—1 Use default. 
EXFLAG Execute file flag: 
0 Take input from execute files or COMDEV. 
1 Take input from COMDEV only. 
—1 Use default. 
BUF Array receiving line of characters. 
CNT Actual character count (CNT <= MAX). 
The terminating character of the line: 
0 MAX characters output. 
‘8D'X Carriage return. 


’93'X Control-S. 


See TYPIN. 


SUBTRACE 


SYNTAX 


PURPOSE 


INPUT 


FUNCTION 
RETURN 


NOTE 


SUBTRACE 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


SUBTRACE(ARG) 

Toggles trace map output. 

ARG ‘ON’ Enables trace printout. 
‘OF’ Disables trace printout. 


0 Successful completion. 
—1 Illegal argument passed. 


See Section 3, Subroutine Trace, for further explanation. 
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TAPE(UNIT,KYWD) 

Processes various tape control requests. 

UNIT Two character tape unit number for processing request 
KYWD Keyword specifying type of request: 


Tape Status Checks 
(See FUNCTION RETURN below): 


TR Is tape unit ready? 

TW Write-enabled? 

TF Last record? 

TL Is tape at load point? 
TP Type of parity setting. 
TB Packed records? 

TG Checks for EOT ERR. 
TT Checks for 9-track unit. 
TE Is end-of-tape on? 

IR Is tape rewinding? 


Tape Control Operations 
(No FUNCTION RETURN): 


BR Skip back one record. 
FR Skip forward one record. 
BF Skip back one file. 

FF Skip forward one file. 

ER Erase 2.5 inches of tape. 
WF_ Write EOF. 

RW Rewind. 


Set Tape Control Features 
(No FUNCTION RETURN): 


SO Odd parity. 

SE Even parity. 

SU Unpacked records. 

SP Packed records. 

SG _ Generate an error if EOT passed. 
SD _ No error if EOT passed. 


FUNCTION | 


RETURN 


TAPE 
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Tape Status Checks only: 


Keyword Return 
TR 0 
TW 0 
TF 0 
TL 0 
TP 0 
TB 0 
TG 0 
TT 0 
TE 0 

IR 0 


Meaning 


Unit not ready. 
Write ring in. 

Last record read was not 
an end-of-file mark. 
Not at load point. 
Odd parity. 
Unpacked records. 
End-of-tape error set. 
Nine- Track unit. 
End-of-tape not on. 
Unit not rewinding. 
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TAPENW(UNIT,ARGLST) 


Processes a tape request using no-wait I/O. 


UNIT 


ARGLST 


Two character tape unit number for processing request. 


Two word array: 


-ARGLST(1)_ 


Type of request. Can have any value of the KYWD argument 
to the TAPE routine. 


ARGLST(2) 
Status return from the requested test (in ARGLST 


(1)) — not valid until TESTIO returns an I/O complete. The 
value is equivalent to the function return from subroutine 


TAPE (for KYWD = ARGLST (1)). 


Address of IOFLAG assigned. 


This is the no-wait entry. There is no guarantee that the request will actu- 
ally be issued no-wait, but the |/O flag returned must be tested before the 
operation or status return can be considered to be valid. 
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TESTIO(IOFLAG) 
Tests an IOFLAG for !/O completion. 


IOFLAG returned by an |/O request call. 


0 1/O not done. 
—1 IOFLAG is bad or no flag assigned to request. 
1 |/O done and flag released or no IOFLAG for request. 


e If the FUNCTION RETURN is zero, TESTIO must be called again later 
for this IOFLAG. 


e Any errors detected during the |/O request will invoke the system error 
handler. The user must call SRTESTIO to return the error value. 


TESTTAPE(NAME) 
Validates a task unit name for an attached tape unit. 
NAME Two-character name. 


0 NAME is valid task unit name for tape unit. 
— NAME is invalid or not a tape unit. 
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TIME(ARR) 


Gives the current time: 


ARR Current time (four-word array): 
1 Year (right two digits). 
2 Day of year (starting at one). 
3 _ Minutes of day. | 
4 Tenths of seconds. 


TOGGLE(DEVICE,SWT) 
Checks real time toggle bits and sets non-real time toggles to their proper 
values. 
DEVICE 0 Process real time toggles only. 
1 Also toggle HARDEV according to SWT. 
2 Also toggle COMDEV according to SWT. 
SWT —1 Turn off. 
0 Toggle. 
1 Turn on. 
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THE TRAVERSE 
PACKAGE 


Traverse TRAVERSE walks through portions of the system file structure. For each 
Process file encountered during file structure tree walk, it outputs filename and 
catalog information. 


TRAVERSE visits nodes* of a catalog to processes files. The actual pro- 
cessing, however, is left to the discretion of the calling routine. The calling 
routine must successively call each of the four Traverse routines 
(TRAVERSE, NEXTNODE, and ABORTRAV) to perform a tree walk. 
There are three major processing steps in executing the tree walk. 


Step One First, the catalog must be “‘activated’’ with TRAVERSE. This routine 
initializes the tree walk by setting up the catalog to be traversed. It also 
establishes the kinds of information returned about nodes and files 
encountered during the walk. TRAVERSE is called once to start the waik. 


Step Two While traversing the catalog structure, the caller requests the ‘‘next’’ node 
or file as needed (entry NEXTNODE). NEXTNODE its executed repeatedly 
until it traverses the entire catalog. 


Step Three When the traverse is completed, ‘‘deactivate’’ the primary catalog using 
ABORTRAV. ABORTRAV may be called at any time to terminate a 
Traverse. It must be called to do standard cleanup following an error 
return. 


*In general, a node is equivalent to a catalog. The catalog designated as an 
argument to the TRAVERSE routine becomes the primary node or tree. 
All other nodes are sub-trees. A file is a terminating leaf on a tree or sub- 
tree. If requested, TRAVERSE will return nodes as files. 
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TRAVERSE(NAME,ARRAY) 

Initializes the TRAVERSE package by setting up the catalog to be traversed 

and the information to be returned for each file. TRAVERSE must be called 

at the start of each walk, but it may not be called more than once. 

NAME An integer array of variable size containing the catalog name in 
FM name format. This argument need not be preserved for the 
remainder of the traversal. 

(Word) 


(0) Number of characters in the catalog name. 


(1-n) Catalog name in packed character format (includes terminat- 
ing !). 


ARRAY A 20-word integer array that defines the details of the walk to 
be performed. 


(Word) 
(0) Option flags for tree walk: 
Bit (Leftmost bit = 0.) 
0-7 Reserved 
8 OFF Return all IND values (IND is a one-word 
character string returned by NEXTNODE). 
ON Return only if IND=OK or IND=ND. 
9 OFF Call the system error routine if an error occurs. 


ON Function return any error codes. 
10 OFF Return all types of files. 


ON Return only file types specified in ARRAY 
(5-20). 


11 ON Return only files dated before date in 
ARRAY (1-2). 
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12 ON Return only files dated since date in ARRAY 
(3-4). 


13 OFF Do not return temporary files on IND= OK. 


ON Return temporary files on IND= OK. 


14 OFF Execute tree walk from left to right, buttom up 
(See NOTE). 


ON Execute tree walk from right to left, top down 
(See NOTES). 


15 OFF Traverse one level of catalog structure. 
ON Traverse ail levels of catalog structure. 
(1-2) With Word 0, Bit 11 ON, BEFORE date in FM name format. 
(3-4) = With Word 0, Bit 12 ON, SINCE date in FM name format. 
(5-20) File types to return on IND= OK. 


FUNCTION With ARRAY(0) Bit 9 set: 

RETURN 
0 Successful TRAVERSE. 
OTHER Appropriate error code. 


ERRORS ‘CO05’x Catalog not found. 
‘C03B’x PDL overflow. 
‘C045’x No channel avalable for new level. 


NOTES @ See descriptions of FREAD, ROPEN, and CLOSE for other error codes 
returned. 


e For a description if File Manager errors, refer to SYSNEWS.ERROR.FM. 
e ARRAY(0) Bit 14 ON: 
If the new entry is a catalog, push the current catalog onto the stack and 
process the new catalog. When the new catalog is finished; pop the 


stack and return the catalog as a normal entry. If the entry is not a 
catalog, then return the entry. 
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e ARRAY(0) Bit 14 OFF: 


Make two passes over each catalog. In the first pass, return each entry 
as encountered. In the second pass; if the new entry is a catalog, push 
the current catalog onto the stack and process the new catalog. If the 
entry is not a catalog, then ignore it. 


NEXTNODE(IND,NAME,ARRAY) 


Returns the next node or file in the catalog to be processed by the calling 
routine. Outputs the file or catalog name. 


IND 


Describes the current status of the traversal and indicates the 
output to NAME and ARRAY. The output to IND is a one-word 
literal character string, as follows: 


=LP Start of catalog. 
NAME Node name. 
ARRAY ROPEN extended array. 


= OK Process this node. 
NAME Node name. 
ARRAY Catalog entry for NAME. 


= RP End of catalog. 
NAME Node name. 
ARRAY Blank. 


= ND End of TRAVERSE. 
NAME Blank. 
ARRAY Blank. 


=PT Node is a catalog that cannot be traversed because of 
protection or modification. In this page IND = PT takes 
the place of IND=LP and IND= RP returns. IND= OK 
returns are not made. 
NAME Node name. | 
ARRAY Catalog entry for node. 


TRAVERSE 
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ABORTRAV 
SYNTAX ABORTRAV 
PURPOSE Terminates the tree walk. It may be called at any point to abort a tree walk 


or cleanup after an error return. At the end of the traverse, (IND =ND) 
NEXTNODE will call ABORTRAV. 
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TREAD(UNIT,CNT,ARR) 


Reads a physical record from magnetic tape. If necessary, it unpacks the 
record. 


UNIT Two-character task unit name for tape unit 

CNT Maximum number of words to be read into ARR. 
ARR Array of data from tape record 

Actual record length in words. 


Packed records on a seven-track unit may cause more than one physical 
tape record to be read. 
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TREADNW(UNIT,ARGLST,ARR) 


Reads a physical record from magnetic tape and returns the address of the 
1/O flag. This is the no-wait version of TREAD. 


UNIT Two-character task unit name for tape unit. 
ARGLST Two-word array required for the call to the tape handler. 
ARGLST(1) is the maximum number of words to be read. 
ARGLST(2) is set to the number of words actually read 
and is not valid until TESTIO returns an 1/O 
complete. 
ARGLST(2) Count of words actually read. 
ARR _ Array containing data from tape record. 
Address of IOFLAG assigned 
e Appiications programs should call TESTIO before attempting to use the 


data. 


e On a seven-track tape unit with packed records, all the advantages of 
NO-WAIT I/O are lost since the records have to be unpacked. 


e Applications programs do not require special handling. 
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TSTBIT(STRING, INDEX) 
Returns the value of a bit. 


STRING Bit string array. 


INDEX Bit index into STRING (leftmost bit is 0). 


0 Bit is OFF. 
1 Bit is ON. 


TSTZERO(DBNUM) 
Tests double integer for zero value. 
DBNUM Double integer to be tested. 


0 DBNUM equals zero. 
#0 DBNUM not equal to zero. 
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NOTE 
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TWRITE(UNIT,CNT,ARR) 


Writes a physical record onto magnetic tape. If necessary, the record is 
unpacked. 


UNIT |= Two-character task unit name for tape unit. 
CNT Record length (word count) 

ARR Record data buffer 

ARR Contents of the buffer. 


More than one physical tape record may be written when packed records 
are used on a seven-track unit. 
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TWRITENW 
SYNTAX — TWRITENW(UNIT,ARGLST,ARR) 
PURPOSE “Writes a physical record on magnetic tape then, instead of waiting, it 
returns the I/O flag. 
INPUT UNIT Two-character task unit name for tape unit. 
ARGLST Two-word array required for call to tape handler. 
| ARGLST(1) Number of words to write. 
ARR Record data buffer. 
OUTPUT ~~» ARGLST(2) = Number of words written. 
FUNCTION Address of the !/O flag 
RETURN | } 
NOTES e The application program should call TESTIO before attempting to use 


the data in ARGLST. 

® Ona seven-track tape unit with packed records, ali the advantages of 
NO-WAIT I/O will be lost. Once the records are packed, more than one 
physical record may be written for each logical record passed. 


e In application programming, all calls to TWRITENW are no-wait. 
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TYPE(CNT,LINE) 

Outputs a line of characters to the COMDEV. 

CNT The number of characters to be output. 

LINE Packed character string. 

e TYPE inserts a carriage return and a line feed at the end of the line. 

@ The line will also be output to the HARDEV if the hard copy toggle is on. 


e TYPE calls CHKINTR after each line is output, so characters may be 
removed from the TIS (see CHKINTR). 


e See TYPOUT and LP. 
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TYPEDBHX | 

SYNTAX TYPEDBHX(NUMBER) 

PURPOSE Outputs a double integer in hexadecimal form. 

INPUT NUMBER Double integer to convert for output 

OUTPUT Two blanks, four hex digits, a slash, then the last four hex digits. 
TYPEDBI 

SYNTAX TYPEDBI(NUMBER) 

PURPOSE Outputs a double precision integer in decimal form. 

INPUT NUMBER Double precision integer. 

OUTPUT The number is preceded by two blanks. Leading zeros are suppressed. 


5-182 


TYPEHEX 


The information and drawings contained herein are the sole property of Computervision 
Corporation. Use of this document is reserved exclusively for Computervision customers 
and personnel. Reproduction of this matter in whole or in part is forbidden without the 
express written consent of Computervision. 


TYPEHEX 
SYNTAX TYPEHEX(NUMBER) 
PURPOSE Outputs an integer in hexadecimal form. 
INPUT NUMBER _ 16-bit integer. 
| OUTPUT Four hex digits — leading zeros are not suppressed. 
TYPEINT 
SYNTAX TYPEINT(NUMBER) 
PURPOSE Outputs an integer in decimal format. 
INPUT NUMBER Integer. 
OUTPUT NUMBER ls right-justified, padded with blanks, and output in a six- 


character field (equivalent to a FORTRAN [6 format). 
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TYPEOK(FILENAME,MESSG1,MESSG2) 
Tests for OK response to a message printed on the COMDEV. The 
response may come from the COMDEV or from an execute file. 
Special Feature 

If the response is QUIT, then TYPEOK does a 

LBLGO to —3. This is identical to an INTR- 

QUIT <ESC>(Q. 
FILENAME Filename in standard FMNAME format, or a third message. 
MESSG1 First message: 


(1) Character count. 
(2-n) Message characters. 


MESSG2 Question asked ‘TYPE OK TO’ MESSGz2: 


(1) Character count. 
(2-n) Message characters. 


0 Response was OK. 
—1 No OK response — COMDEV may have been detached. 


lf a third message is used and the final character in the message is (!), the 
(1) will not be printed (as in a filename). 


Ean ENG 
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TYPIN(MAX,BUF,CNT) 

Inputs a line of characters from the COMDEV or an execute file. 

MAX = Maximum number of characters to be input. 

BUF Destination Array for line of characters. 

CNT ~~ Actual character count (CNT <MAX). 

e TYPIN inputs characters until a carriage return is found, places the line 
in BUF and returns the actual character count in CNT. If MAX 


characters are input before a carriage return, the line is considered com- 
plete. 


Unless an execute file is active, input is read from the COMDEV. 


Any special system characters in the input will be processed as they are 
received. The line stored in BUF will reflect their actions even though the 
characters themselves will not be stored. A line may be restarted, a 
character deleted, and so forthh HARDCOPY and NOPRINT toggle 
characters are processed in the same way. 


See also STYPIN, TYPEOK, TYPOUT. 


TYPOUT(CNT,STRING) 


Outputs a string of characters to the COMDEV (and to the HARDEV if the 
toggle is on). 


CNT Number of characters to be output. 
STRING Packed character string. 


® TYPOUT does not add a carriage return or line feed at the end of the 
line; the cursor is left after the last character typed. 


e See also, TYPE. 
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UNATTACH 
SYNTAX UNATTACH(NAME) 
PURPOSE Detaches a unit from a task. 
INPUT NAME Two-character (1 word) name assigned to the unit. 
— 1 to detach all units. 
FUNCTION 1 Successful completion. 
~ RETURN 0 The name is bad, or COMDEV is released and there is another unit 


named ‘SD’. 
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WAITIO(IOFLAG) 

Changes a NOWAIT 1/0 request into a WAIT I/O request. 
IOFLAG Address of a valid IOFLAG. 

Error messages: 


FOO5 Called with invalid IOFLAG address. 
FOO6 Error was generated during the |/O request. 


WAITIO 


WAITIO resets the IOFLAG value. This eliminates any need to call 


TESTIO(IOFLAG). 
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The general sequence for writing to a binary sequential file with byte- 
oriented counts would be to open with WRITFILE, write blocks of words 
with WRITBYTE, and close with WRITCLOS. 


WRITBFIL(FSB,BUF,BUFSIZ,-FNAME,OPTIONS) 


Opens a binary sequential file for writing with byte-oriented counts. 


FSB(11) 


BUF 
BUFSIZ 


FNAME 


OPTIONS 


File Status Block. FSB(1) must equal one for the first call 
buffer. 


Disc buffer. 
Size of BUF (sectors). 
Filename: 


FNAME(1) Byte count of name, including final (1). 
FNAME(2-N) Filename with (!). 


Bit (Leftmost bit is 0.) 


7 ON Create new catalogs as needed. 
OFF Error if catalog level is missing. 


WRITBYTE 


SYNTAX 


PURPOSE 


INPUT 


WRITBCLS 
SYNTAX 
PURPOSE 


INPUT 


WRITBFIL 
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WRITBYTE(FSB,BUF,COUNT,BLOCK,OFFSET) 
Writes a record to an open binary file (see WRITBFIL). 
FSB(11) File Status Block. 

BUF Disc buffer. 

COUNT Number of bytes in the record. 

BLOCK Array containing the record to be written. 


OFFSET Byte offset in the array (counted from 0). 


WRITBCLS(FSB, BUF) 
Closes a binary sequential file opened with WRITBFIiL. 
FSB(11) File Status Block. 


BUF Disc buffer. 
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The general sequence for writing to a binary sequential file would 
be to open with WRITFILE, write blocks of words with WRITBLOK, 
and close with WRITCLOS. 

These three routines can also be used to write a random access binary file. 
There are three functions available for using the sequential access pointer 
of a random access file (see Section 5, The READFILE Utility). A call to 
READMARK reads the position of the pointer, while READPOS and 
READTOP can be used to move the pointer. 

An existing file may be modified in place by using MODIFILE to open the 


file. READBLOK, WRITBLOK, READPOS, READMARK, and READTOP 
can all be used to change data in the file. To close it, use WRITCLOS. 


WRITFILE(FSB, BUF, BUFSIZ, FNAME, OPTIONS) 
Opens a binary sequential file for output. 

FSB File Status Block. 

BUF Disc buffer. 

BUFSIZ Size of disc buffer in sectors. 


FNAME Filename in FM format: 


Word 1 Character count (including !). 
Word 2-n Filename (terminated by !). 
OPTIONS(1) 
Bit (Leftmost bit is 0.) 
2 ON Initial number of sectors to allocate is in 
OPTIONS(2-3). 


OFF Allocate default number of sectors. 


3 ON Force the file to be contiguous. 
OFF Non-contiguous sectors may be allocated. 


INPUT 
(Continued) 


FUNCTION 
RETURN 


ERRORS 


NOTES 


WRITFILE 
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7 ON 
OFF 
15 ON 
OFF 
OPTIONS(2-3) 


OPTIONS(1) bit 15 ON: 


0 Indicates no error 
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Create new catalogs as required. 
Generate error if all catalogs do not exist. 


Error condition results in error FLAG re- 
turned as function name. 
Error results in the call ERROR(FLAG). 


Number of sectors to allocate when file is 
opened (only if bit 2 is ON). 


FLAG Indicates type of FILE MANAGER ERROR 


For description of FILE MANAGER ERRORS, refer to: 


SYSNEWS.ERROR.FM. 


e The FSB (File Status Block) is described in LIB.FM.READFILE. 


e No routines in the READFILE family contain local variables to maintain. 
Only the integrity of FSB and BUF is important. 
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WRITBLOK(FSB, BUF, COUNT, BLOCK) 

Writes, or modifies, a block of words in a binary sequential file. 
FSB(11) File Status Block. 

BUF Disc buffer. 

COUNT Number of words to write. 

BLOCK Array of words to write. 


Before WRITBLOK is called, the file must be opened with MODIFILE or 
WRITFILE. 7 


WRITCLOS 
SYNTAX 
PURPOSE 


INPUT 
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WRITCLOS(FSB,BUF,OPTIONS) 


Closes a binary sequential file. 


FSB File Status Block. 
BUF Disc buffer. 
OPTIONS(1) 
‘Bit (Leftmost bit is 0.) 

0 ON If open for create, delete the file. If the file is 
open for create with supersede, do not 
supersede the file. Instead, delete the new file 
and preserve the original). 

1 ON If bit 0 is OFF, change user attribute values to 
OPTIONS(2) and OPTIONS(3). 

2 ON Do not update the access date. 

3 ON If bit 0 is OFF, change the file size the value 
specified in OPTIONS(4-5). 

4 ON If bit 0 is OFF, change the creation date and time 
to values specified in OPTIONS(6-7). 

5 ON If bit 0 is OFF, change the system attibute words 
to OPTIONS(7-8). 

15 ON Routine function returns errors generated by 
CLOSE. 

OFF Errors are processed by the system error handler. 
OPTIONS(2-3) User attribute values (if bit 1 on). 
OPTIONS(4-5) Total sector count for file (if bit 3 is ON). 
OPTIONS(6-7) Creation time and date for file (if bit 4 is ON). 
OPTIONS(8-9) System attribute words (if bit 5 is ON). 
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XEQTCOMM 
SYNTAX XEQTCOMM(COUNT, COMMAND) 
PURPOSE Executes a system command passed as a subroutine argument. 
INPUT COUNT Character count of command string. 
COMMAND Command string to be executed. 
NOTE This routine does not return to the calling code after invoking the system 


command. 
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Section 6 
SYSTEM FORMATS 


This section describes: 


¢ Common system data structures. 
e File formats. 
e Data types and how they are represented in CGOS 200. 


Bits are generally numbered from left to right, starting with bit 0. This is 
true for: 


e All CGOS 200 manuals. 

e All CGOS 200 subroutine descriptions, code and data structures. 

e The front panels and backplanes of all Computervision CPUs (CGP-100) 
and the CGP-100 maintenance panel. 


SINGLE WORD BIT NUMBERING: 
LEFT BYTE RIGHT BYTE 
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 «15 
DOUBLE WORD BIT NUMBERING: 


_ | FIRST WORD 


oO 1 2 3 4 5 6 7 8 9 10 11 12 13 14 = 18 


| 7 SECOND WORD 


‘46617 18 19 20 21 22 23 24 25 26 27 28 29 30 31 


Bits are numbered from right to left in CADDS application routines. 
Numbering schemes may vary for peripherals that interface with 
Computervision systems. 


For the byte YY hexadecimal: 
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CHARACTER For the character whose ASCII code is YY hexadecimal: 
FORMAT 
0 | 7 8 | 15 


AO hexadecimal is the byte for the blank ASCII character marked parity. 


Character Character strings are packed two characters per-word starting with the left 
. String Format byte of the first word. If the string has an odd number of characters, it is 
left-justified and padded with a blank (ASCII code AO hexadecimal). 


The character string ‘ABCD’ is stored as: 


WORD 1 


Pe 
woro2 [cf > 
: 0 7 
The character ““A” is stored as: 


0 7 8 15 


NOTE ' All characters are stored as seven-bit ASCII codes with the most signifi- 
7 cant eighth bit set. BCD codes are never used, even when explicitly men- 
tioned in the documentation. | 


DATE AND SYSTEM (FILE MANAGER) DATE AND TIME FORMAT 
TIME FORMATS 
| | | «YEAR MONTH DAY 
_ DATE: a. (0-63) (1-12) (1-31 
0 1 6 7 10 11 15 


where PM is AM/PM indicator, ON for PM, 
OFF for AM, and Year is number of years since 
1960. | 
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0 : 


SECONDS 
a (0-43199) 
| 45 


where Seconds is the number of seconds in a 
half-day. 


INTERNAL TIME FORMAT 


YEAR DAY 
CLOCK (1): RIGHT 2 DIGITS (1-366) 
O 


15 


0 15 
16 31 


CLOCK (1): 
CLOCK (2): 


(1 tick = 10 milliseconds) 


EXTERNAL TIME FORMAT 


0 15 
| YEAR | 
TIME (1): RIGHT 2 DIGITS 
— TIME (1): 
TIME (2): - MINUTES 
TIME (3): TENTHS OF SECONDS | 
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TEXT FILE Under the File Management catalog structure: 
FORMAT 
Word Contents 
(1-2) Double word indicating number 
of sectors in file. 
(3) Number of bytes of useful infor- 
mation in last sector of file. 
(4) 0 


(5-N) Line data for file. 


Each line consists of a four-byte header followed by the N characters from 


that line. 
HEADER: 
/RESERVED | TAB | RESERVED| CNT 
BYTEO BYTE 1 BYTE2 BYTE3 


TAB Number of blanks to insert in front of text. 
CNT Number of bytes of text in this line. 


Floating Floating Point (Real) Format provides an approximate representation for all 

Point Format numbers within a very wide range. Allocation of more bits per number 
(greater PRECISION) increases accuracy by decreasing the difference be- 
tween consecutive numbers. Three fields of bits are used to represent a 
number in Floating Point Format: 


SIGN EXPONENT MANTISSA | 


Sign SIGN is a one-bit field. If the bit value is one, the floating Point number is 
negative. If the bit is zero, then the number is positive. | 


Exponent An eight-bit field where values are stored in two’s complement binary with 
an inverted sign bit. This form of storage is often called ‘‘excess 128” as 
the result of adding 128 to the normal two’s complement binary value. 


EXPONENT is the power of two by which the fraction in the MANTISSA 
should be multiplied to reconstruct the floating point number. Thus, the 
pattern ‘80’x within the field (which has value of 0) means that the (frac- 
tional) MANTISSA should be multiplied by 2**0, or 1; i.e., the mantissa is 
the represented (fractional) number. Similarly, patterns of ’‘81’x or more 
(values > 0) imply multiplication by powers of two (left shift) during 
reconstruction. 


Mantissa 


STORAGE 
FORMATS 


Single 
Precision 
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Note 


Two asterisks (**) mean ‘‘raised to the power 
of’’. 


A variable length field, 23 bits in SINGLE precision format or 55 bits in 
DOUBLE precision format. MANTISSA stores the magnitude of the frac- 
tion thAT reconstructs the floating point value when multiplied by EXPO- 
NENT. For accuracy, the EXPONENT and MANTISSA are adjusted until 
the fraction represented by the MANTISSA falls into the range: 


1/2 < fraction <1 


This is called ‘‘normalizing’’ the fraction. For a normalized fraction 
represented in binary, the first bit to the right of the binary point is the 
most significant bit, and its value is always one. To extend precision, this 
bit is NOT explicitly stored. The most significant stored bit in the mantissa 
field is actually the bit representing 1/4; thus the 1/2 bit is assumed to 
equal one. This allows the mantissa to store 24 significant bits for SINGLE 
precision, and 56 significant bits in DOUBLE precision. This hidden bit is 
called a ‘‘phantom bit representation” for the mantissa. 


SINGLE precision floating point format allocates two memory words, 
while DOUBLE precision allocates four words. In either precision, the first 
memory word contains the SIGN, EXPONENT, and most significant bits of 
MANTISSA fields: | 


BIT 0 1 8 9 15 
VALUE: 2**-2 2**-8 


[siGN] EXPONENT | ~~ MANTISSA 
| MANTISSA 


BIT: 16 31 
VALUE: | 2**.9 2**-24 
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Double 


Precision BIT: 0 8 9 15 
2**2 2**.8 


VALUE: 
wawrissa 
BIT: 48 63 


VALUE: 2**-41 | 2**-56 


LOC n: | 
LOC n+1: 


LOC n+2: 


LOC n+3: 


Zero Zero is the only number not normally represented in the above formats: it 
has no most significant bit to be normalized. In either SINGLE or DOUBLE 
precision, the number in the EXPONENT and MANTISSA is true zero 
(0.0), rather than the smallest possible nonzero number. Calculations 
which produce values less than or equal to the smallest possible nonzero 
number are considered to have produced a zero (0.0) instead. Similarly, 
minus zero (sign bit being the only nonzero bit) is converted to true zero 
(all bits zero). | 

Range In absolute value, a floating point number has the following ranges: 
SINGLE Precision: 

1/2 x 2**-128 to (1 - 2**-24) x 2**127 
DOUBLE Precision: 
1/2 x 2**-128 to (1 - 2**-56) x 2**127 


This is approximately 10**-38 to 10**38. 


Accuracy SINGLE Precision: 
1 part in 2**24 (7 decimal digits) 
DOUBLE Precision: 


1 part in 2**56 (16 decimal digits) 


INTEGER 
FORMAT 


MAGNETIC 
TAPE FORMAT 
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Each number is represented exactly in INTEGER format. The difference 
between consecutively represented numbers is ONE (unity), and thus in- 
dependent of PRECISION. Allocation of more bits per number extends the 
range of representable numbers, but not the accuracy of each number. 


Standard two’s complement notation for INTEGERS ailows both positive 
and negative numbers to be represented as 16 bits (SINGLE) or 32 bits 
(DOUBLE) precision (these correspond to one word or two words, respec- 
tively). 


SINGLE integer range: 

— 32,768 to 32,767 inclusive 
DOUBLE integer range: 

—2,147,483,648 to 2,147,483,647 inclusive 
Tape controllers read or write up to ‘2000’hex frames as a single record. 
This corresponds to ‘1000’hex words on 9-track tape. High level system 
tape I/O routines recognize this and allow transfers of ‘1000’hex words per 
call. 
Two frames of tape store one CGP-100 16-bit word. Each frame consists of 
a parity bit followed by eight bits of data. The word is converted so that 


bits 0-7 are stored in the first frame and bits 1-15 are stored in the second 
frame. 


FRAME 1 


FRAME 2 
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7-Track Tape 


PACKED 
FORMAT 


Packed and unpacked formats are used. Machine words cannot be evenly 
divided into tape frames on 7-track tape, so Packed Format is used. Each 
7-track tape frame consists of a parity bit followed by 6 bits of data. One 16 
bit machine word is ‘‘packed”’ into 3 tape frames. Frame 1 of the tape has a 
binary 10 in the first two bits followed by the data from memory word bits 
0-3; frame 2 contains bits 4-9 from the memory word; and frame 3 contains 
bits 10-15. 


MEMORY TAPE 
0 3 4 9 10 15 0 3 
PIS THE PARITY BIT Pp FRAME 2 
4 9 
10 15 


Since memory words require three frames on 7-track tape, the entire 
transfer may require more than one tape record. To resolve this problem, 
the system software splits the complete request into multiple tape records. 
These records are at most ‘400’hex words long and are begun with a three 
word header (9 frames). The header format is: 


Word 0: Physical record number for this logical record (= 1). 
Word 1: Total number of physical records in this logical record (= 1). 
Word 2: Maximum physical record size (‘400’hex) 
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OLD PACKED The system supports Old Packed format to allow reading of tapes prepared 

FORMAT by earlier CADDS O/Ss. Old Packed format is only supported for reading 
tapes. It ‘packs’ each memory word into four tape frames, with four 
memory word bits per frame. The first two bits of each frame contain the 
binary value 11. Each tape record begins with a twelve-frame header in the 
same form as the header for Packed Format. 


MEMORY TAPE 


3 4 78 11 12 


P 1S THE PARITY BIT 7c FRAME 2 


4 7 


Pla] __] Frames 


8 11 


[a] _] Frame 4 


12 15 
UNPACKED This format transfers to tape exactly like 9-track format, two frames per 
FORMAT word. Unfortunately, 7-track tape has only six bits per frame, so four bits 


(0-1 and 8-9) are lost from each memory word. 


MEMORY TAPE 


. FEE ent 


BITS XX ARE LOST. 


10 15 
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